@subsimplicity/pi-extension-linear 0.0.1

package/src/client.ts

@@ -0,0 +1,571 @@
+/* eslint-disable n/no-unsupported-features/node-builtins */
+
+import type {
+  LinearComment,
+  LinearCreateIssueParams,
+  LinearIssue,
+  LinearIssueSummary,
+  LinearSearchParams,
+  LinearState,
+  LinearTeam,
+  LinearUpdateIssueParams,
+  LinearViewer,
+} from "./types.ts";
+
+type JsonValue =
+  | JsonValue[]
+  | boolean
+  | number
+  | string
+  | { [key: string]: JsonValue | undefined }
+  | null;
+
+type JsonObject = Record<string, JsonValue | undefined>;
+
+interface GraphQLResponse<T> {
+  data?: T;
+  errors?: {
+    extensions?: Record<string, unknown>;
+    message: string;
+    path?: unknown[];
+  }[];
+}
+
+export class LinearApiError extends Error {
+  public constructor(
+    message: string,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "LinearApiError";
+  }
+}
+
+const LINEAR_GRAPHQL_ENDPOINT = "https://api.linear.app/graphql";
+const LINEAR_PAGE_SIZE = 100;
+const ISSUE_KEY_PATTERN = /\b[A-Z][A-Z0-9]+-\d+\b/g;
+
+const ISSUE_SUMMARY_FIELDS = `
+  id
+  identifier
+  title
+  description
+  url
+  priority
+  priorityLabel
+  estimate
+  dueDate
+  createdAt
+  updatedAt
+  state { id name type position }
+  team { id key name }
+  assignee { id name displayName email }
+  delegate { id name displayName email }
+  project { id name url }
+  labels { nodes { id name color } }
+`;
+
+function getAuthorizationHeader(): string | undefined {
+  const accessToken = process.env.LINEAR_ACCESS_TOKEN?.trim();
+  if (accessToken) return `Bearer ${accessToken}`;
+
+  const apiKey = process.env.LINEAR_API_KEY?.trim();
+  if (apiKey) return apiKey;
+
+  return undefined;
+}
+
+function clampLimit(
+  value: number | undefined,
+  fallback: number,
+  max = 50,
+): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.max(1, Math.min(max, Math.floor(value)));
+}
+
+function clampCount(
+  value: number | undefined,
+  fallback: number,
+  max = 50,
+): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.min(max, Math.floor(value)));
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  return trimmed;
+}
+
+function compactObject<T extends JsonObject>(input: T): T {
+  const output: JsonObject = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) output[key] = value;
+  }
+  return output as T;
+}
+
+export function extractIssueKeys(text: string): string[] {
+  return [...new Set(text.match(ISSUE_KEY_PATTERN) ?? [])];
+}
+
+export function hasLinearCredentials(): boolean {
+  return getAuthorizationHeader() !== undefined;
+}
+
+export class LinearClient {
+  public async graphql<T>(
+    query: string,
+    variables: JsonObject = {},
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const authorization = getAuthorizationHeader();
+    if (!authorization) {
+      throw new LinearApiError(
+        "Linear credentials not configured. Set LINEAR_API_KEY for personal API-key auth or LINEAR_ACCESS_TOKEN for OAuth bearer-token auth.",
+      );
+    }
+
+    const response = await fetch(LINEAR_GRAPHQL_ENDPOINT, {
+      body: JSON.stringify({ query, variables }),
+      headers: {
+        Authorization: authorization,
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+      signal,
+    });
+
+    const text = await response.text();
+    let payload: GraphQLResponse<T>;
+    try {
+      payload = JSON.parse(text) as GraphQLResponse<T>;
+    } catch (error) {
+      throw new LinearApiError(
+        `Linear API returned non-JSON HTTP ${String(response.status)}: ${text.slice(0, 500)}`,
+        error,
+      );
+    }
+
+    if (!response.ok) {
+      const message = payload.errors?.map((item) => item.message).join("; ");
+      throw new LinearApiError(
+        `Linear API HTTP ${String(response.status)}${formatOptionalMessage(message)}`,
+        {
+          errors: payload.errors,
+          rateLimit: readRateLimitHeaders(response.headers),
+        },
+      );
+    }
+
+    if (payload.errors?.length) {
+      throw new LinearApiError(
+        payload.errors.map((item) => item.message).join("; "),
+        {
+          errors: payload.errors,
+          rateLimit: readRateLimitHeaders(response.headers),
+        },
+      );
+    }
+
+    if (!payload.data) {
+      throw new LinearApiError("Linear API response did not include data.", {
+        rateLimit: readRateLimitHeaders(response.headers),
+      });
+    }
+
+    return payload.data;
+  }
+
+  public async viewer(signal?: AbortSignal): Promise<LinearViewer> {
+    const data = await this.graphql<{ viewer: LinearViewer }>(
+      `query LinearViewer { viewer { id name displayName email } }`,
+      {},
+      signal,
+    );
+    return data.viewer;
+  }
+
+  public async teams(signal?: AbortSignal): Promise<LinearTeam[]> {
+    const teams: LinearTeam[] = [];
+    let cursor: string | undefined;
+    let hasNextPage = true;
+
+    while (hasNextPage) {
+      const data = await this.graphql<{
+        teams: {
+          nodes: LinearTeam[];
+          pageInfo: { endCursor: string | null; hasNextPage: boolean };
+        };
+      }>(
+        `query LinearTeams($after: String) {
+          teams(first: ${String(LINEAR_PAGE_SIZE)}, after: $after) {
+            nodes { id key name }
+            pageInfo { hasNextPage endCursor }
+          }
+        }`,
+        compactObject({ after: cursor }),
+        signal,
+      );
+      teams.push(...data.teams.nodes);
+
+      hasNextPage = data.teams.pageInfo.hasNextPage;
+      if (hasNextPage) {
+        if (!data.teams.pageInfo.endCursor) {
+          throw new LinearApiError(
+            "Linear teams pagination indicated another page but did not return an end cursor.",
+          );
+        }
+        cursor = data.teams.pageInfo.endCursor;
+      }
+    }
+
+    return teams;
+  }
+
+  public async resolveTeamId(
+    team: string,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    const trimmedTeam = team.trim();
+    if (isUuidLike(trimmedTeam)) return trimmedTeam;
+
+    const needle = trimmedTeam.toLowerCase();
+    const teams = await this.teams(signal);
+    const match = teams.find(
+      (item) =>
+        item.id.toLowerCase() === needle ||
+        item.key.toLowerCase() === needle ||
+        item.name.toLowerCase() === needle,
+    );
+    if (!match) {
+      throw new LinearApiError(
+        `Could not resolve Linear team '${team}'. Use linear_list_teams to inspect available team ids and keys.`,
+      );
+    }
+    return match.id;
+  }
+
+  public async issue(
+    issueId: string,
+    commentsLimit = 10,
+    signal?: AbortSignal,
+  ): Promise<LinearIssue> {
+    const cappedCommentsLimit = clampCount(commentsLimit, 10);
+    const commentsFragment =
+      cappedCommentsLimit > 0
+        ? `comments(first: $commentsLimit) {
+            nodes { id body createdAt updatedAt user { id name displayName email } }
+          }`
+        : "";
+    const variables = compactObject({
+      commentsLimit: cappedCommentsLimit > 0 ? cappedCommentsLimit : undefined,
+      id: issueId,
+    });
+    const data = await this.graphql<{ issue: LinearIssue | null }>(
+      `query LinearIssue($id: String!${cappedCommentsLimit > 0 ? ", $commentsLimit: Int!" : ""}) {
+        issue(id: $id) {
+          ${ISSUE_SUMMARY_FIELDS}
+          creator { id name displayName email }
+          ${commentsFragment}
+        }
+      }`,
+      variables,
+      signal,
+    );
+    if (!data.issue) {
+      throw new LinearApiError(`Linear issue not found: ${issueId}`);
+    }
+    return data.issue;
+  }
+
+  public async searchIssues(
+    params: LinearSearchParams,
+    signal?: AbortSignal,
+  ): Promise<LinearIssueSummary[]> {
+    const filter = buildIssueFilter(params);
+    const data = await this.graphql<{
+      issues: { nodes: LinearIssueSummary[] };
+    }>(
+      `query LinearSearchIssues($filter: IssueFilter, $includeArchived: Boolean, $limit: Int!) {
+        issues(first: $limit, includeArchived: $includeArchived, filter: $filter, orderBy: updatedAt) {
+          nodes { ${ISSUE_SUMMARY_FIELDS} }
+        }
+      }`,
+      {
+        filter,
+        includeArchived: params.includeArchived ?? false,
+        limit: clampLimit(params.limit, 10),
+      },
+      signal,
+    );
+    return data.issues.nodes;
+  }
+
+  public async myWork(
+    limit: number | undefined,
+    signal?: AbortSignal,
+  ): Promise<{
+    assigned: LinearIssueSummary[];
+    created: LinearIssueSummary[];
+    viewer: LinearViewer;
+  }> {
+    const cappedLimit = clampLimit(limit, 10);
+    const data = await this.graphql<{
+      viewer: LinearViewer & {
+        assignedIssues: { nodes: LinearIssueSummary[] };
+        createdIssues: { nodes: LinearIssueSummary[] };
+      };
+    }>(
+      `query LinearMyWork($limit: Int!) {
+        viewer {
+          id
+          name
+          displayName
+          email
+          assignedIssues(first: $limit, orderBy: updatedAt) { nodes { ${ISSUE_SUMMARY_FIELDS} } }
+          createdIssues(first: $limit, orderBy: updatedAt) { nodes { ${ISSUE_SUMMARY_FIELDS} } }
+        }
+      }`,
+      { limit: cappedLimit },
+      signal,
+    );
+    const { assignedIssues, createdIssues, ...viewer } = data.viewer;
+    return {
+      assigned: assignedIssues.nodes,
+      created: createdIssues.nodes,
+      viewer,
+    };
+  }
+
+  public async states(
+    team: string,
+    signal?: AbortSignal,
+  ): Promise<LinearState[]> {
+    const teamId = await this.resolveTeamId(team, signal);
+    const data = await this.graphql<{
+      team: { states: { nodes: LinearState[] } } | null;
+    }>(
+      `query LinearTeamStates($teamId: String!) {
+        team(id: $teamId) {
+          states { nodes { id name type position } }
+        }
+      }`,
+      { teamId },
+      signal,
+    );
+    if (!data.team) throw new LinearApiError(`Linear team not found: ${team}`);
+    return [...data.team.states.nodes].sort(
+      (a, b) => (a.position ?? 0) - (b.position ?? 0),
+    );
+  }
+
+  public async createIssue(
+    params: LinearCreateIssueParams,
+    signal?: AbortSignal,
+  ): Promise<LinearIssueSummary> {
+    const teamId = await this.resolveTeamId(params.team, signal);
+    const input = compactObject({
+      assigneeId: nonEmpty(params.assigneeId),
+      description: nonEmpty(params.description),
+      dueDate: nonEmpty(params.dueDate),
+      labelIds: params.labelIds,
+      priority: params.priority,
+      projectId: nonEmpty(params.projectId),
+      stateId: nonEmpty(params.stateId),
+      teamId,
+      title: params.title,
+    });
+    const data = await this.graphql<{
+      issueCreate: { issue: LinearIssueSummary | null; success: boolean };
+    }>(
+      `mutation LinearCreateIssue($input: IssueCreateInput!) {
+        issueCreate(input: $input) { success issue { ${ISSUE_SUMMARY_FIELDS} } }
+      }`,
+      { input },
+      signal,
+    );
+    if (!data.issueCreate.success || !data.issueCreate.issue) {
+      throw new LinearApiError(
+        "Linear issueCreate did not return a created issue.",
+      );
+    }
+    return data.issueCreate.issue;
+  }
+
+  public async updateIssue(
+    params: LinearUpdateIssueParams,
+    signal?: AbortSignal,
+  ): Promise<LinearIssueSummary> {
+    const input = compactObject({
+      assigneeId:
+        params.assigneeId === null
+          ? null
+          : nonEmpty(params.assigneeId ?? undefined),
+      description: nonEmpty(params.description),
+      dueDate:
+        params.dueDate === null ? null : nonEmpty(params.dueDate ?? undefined),
+      labelIds: params.labelIds,
+      priority: params.priority,
+      projectId:
+        params.projectId === null
+          ? null
+          : nonEmpty(params.projectId ?? undefined),
+      stateId: nonEmpty(params.stateId),
+      title: nonEmpty(params.title),
+    });
+    if (Object.keys(input).length === 0) {
+      throw new LinearApiError(
+        "linear_update_issue requires at least one field to update.",
+      );
+    }
+
+    const data = await this.graphql<{
+      issueUpdate: { issue: LinearIssueSummary | null; success: boolean };
+    }>(
+      `mutation LinearUpdateIssue($id: String!, $input: IssueUpdateInput!) {
+        issueUpdate(id: $id, input: $input) { success issue { ${ISSUE_SUMMARY_FIELDS} } }
+      }`,
+      { id: params.issueId, input },
+      signal,
+    );
+    if (!data.issueUpdate.success || !data.issueUpdate.issue) {
+      throw new LinearApiError(
+        "Linear issueUpdate did not return an updated issue.",
+      );
+    }
+    return data.issueUpdate.issue;
+  }
+
+  public async commentIssue(
+    issueId: string,
+    body: string,
+    signal?: AbortSignal,
+  ): Promise<LinearComment> {
+    const issue = await this.issue(issueId, 0, signal);
+    const data = await this.graphql<{
+      commentCreate: { comment: LinearComment | null; success: boolean };
+    }>(
+      `mutation LinearCommentIssue($input: CommentCreateInput!) {
+        commentCreate(input: $input) {
+          success
+          comment { id body createdAt updatedAt user { id name displayName email } }
+        }
+      }`,
+      { input: { body, issueId: issue.id } },
+      signal,
+    );
+    if (!data.commentCreate.success || !data.commentCreate.comment) {
+      throw new LinearApiError(
+        "Linear commentCreate did not return a created comment.",
+      );
+    }
+    return data.commentCreate.comment;
+  }
+}
+
+function formatOptionalMessage(message: string | undefined): string {
+  if (!message) return "";
+  return `: ${message}`;
+}
+
+function readRateLimitHeaders(headers: Headers): Record<string, string> {
+  const names = [
+    "x-complexity",
+    "x-ratelimit-complexity-limit",
+    "x-ratelimit-complexity-remaining",
+    "x-ratelimit-complexity-reset",
+    "x-ratelimit-requests-limit",
+    "x-ratelimit-requests-remaining",
+    "x-ratelimit-requests-reset",
+  ];
+  const output: Record<string, string> = {};
+  for (const name of names) {
+    const value = headers.get(name);
+    if (value) output[name] = value;
+  }
+  return output;
+}
+
+function buildIssueFilter(params: LinearSearchParams): JsonObject {
+  const filter: JsonObject = {};
+  const query = nonEmpty(params.query);
+  if (query) {
+    const issueKey = parseIssueKey(query);
+    filter.or = [
+      ...(issueKey
+        ? [
+            {
+              and: [
+                { team: { key: { eqIgnoreCase: issueKey.teamKey } } },
+                { number: { eq: issueKey.number } },
+              ],
+            },
+          ]
+        : []),
+      { searchableContent: { contains: query } },
+      { title: { containsIgnoreCase: query } },
+      { description: { containsIgnoreCase: query } },
+    ];
+  }
+
+  const team = nonEmpty(params.team);
+  if (team) {
+    filter.team = isUuidLike(team)
+      ? { id: { eq: team } }
+      : {
+          or: [
+            { key: { eqIgnoreCase: team } },
+            { name: { eqIgnoreCase: team } },
+          ],
+        };
+  }
+
+  const stateFilter: JsonObject = {};
+  if (params.stateType) stateFilter.type = { eq: params.stateType };
+  const stateName = nonEmpty(params.stateName);
+  if (stateName) stateFilter.name = { eqIgnoreCase: stateName };
+  if (Object.keys(stateFilter).length > 0) filter.state = stateFilter;
+
+  const labels = params.labels
+    ?.map((label) => nonEmpty(label))
+    .filter((label) => label !== undefined);
+  if (labels?.length) {
+    filter.labels = { some: { name: { in: labels } } };
+  }
+  if (params.priority !== undefined) filter.priority = { eq: params.priority };
+
+  const assigneeId = nonEmpty(params.assigneeId);
+  if (assigneeId) filter.assignee = { id: { eq: assigneeId } };
+  const assigneeEmail = nonEmpty(params.assigneeEmail);
+  if (assigneeEmail)
+    filter.assignee = { email: { eqIgnoreCase: assigneeEmail } };
+
+  const projectName = nonEmpty(params.projectName);
+  if (projectName) filter.project = { name: { eqIgnoreCase: projectName } };
+
+  return filter;
+}
+
+function parseIssueKey(
+  value: string,
+): { number: number; teamKey: string } | undefined {
+  const match = /^([A-Z][A-Z0-9]+)-(\d+)$/i.exec(value.trim());
+  if (!match) return undefined;
+
+  const teamKey = match[1];
+  const issueNumber = match[2];
+  if (!teamKey || !issueNumber) return undefined;
+
+  return { number: Number(issueNumber), teamKey };
+}
+
+function isUuidLike(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    value,
+  );
+}
+
+/* eslint-enable n/no-unsupported-features/node-builtins */

package/src/commands.ts

@@ -0,0 +1,140 @@
+import {
+  formatIssue,
+  formatIssueSearch,
+  formatMyWork,
+  formatStates,
+  formatTeams,
+  formatViewer,
+} from "./format.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { LinearClient } from "./client.ts";
+import { updateLinearStatus } from "./status.ts";
+
+export function registerLinearCommands(pi: ExtensionAPI): void {
+  const client = new LinearClient();
+
+  pi.registerCommand("linear-setup", {
+    description: "Check Linear credentials and show the authenticated user.",
+    handler: async (_args, ctx) => {
+      try {
+        const viewer = await client.viewer(ctx.signal);
+        await updateLinearStatus((value) => {
+          ctx.ui.setStatus("linear", value);
+        }, ctx.signal);
+        ctx.ui.notify(`Linear connected as ${formatViewer(viewer)}`, "info");
+      } catch (error) {
+        ctx.ui.notify(errorMessage(error), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("linear-issue", {
+    description: "Fetch a Linear issue: /linear-issue ENG-123",
+    handler: async (args, ctx) => {
+      const issueId = args.trim();
+      if (!issueId) {
+        ctx.ui.notify("Usage: /linear-issue ENG-123", "error");
+        return;
+      }
+
+      try {
+        const issue = await client.issue(issueId, 10, ctx.signal);
+        pi.sendMessage({
+          content: formatIssue(issue),
+          customType: "linear-issue",
+          details: { issue },
+          display: true,
+        });
+      } catch (error) {
+        ctx.ui.notify(errorMessage(error), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("linear-search", {
+    description: "Search Linear issues by text: /linear-search checkout a11y",
+    handler: async (args, ctx) => {
+      const query = args.trim();
+      if (!query) {
+        ctx.ui.notify("Usage: /linear-search text", "error");
+        return;
+      }
+
+      try {
+        const issues = await client.searchIssues(
+          { limit: 10, query },
+          ctx.signal,
+        );
+        pi.sendMessage({
+          content: formatIssueSearch(`Linear issue search: ${query}`, issues),
+          customType: "linear-search",
+          details: { issues, query },
+          display: true,
+        });
+      } catch (error) {
+        ctx.ui.notify(errorMessage(error), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("linear-my-work", {
+    description: "Show Linear issues assigned to and recently created by you.",
+    handler: async (_args, ctx) => {
+      try {
+        const work = await client.myWork(10, ctx.signal);
+        pi.sendMessage({
+          content: formatMyWork(work),
+          customType: "linear-my-work",
+          details: work,
+          display: true,
+        });
+      } catch (error) {
+        ctx.ui.notify(errorMessage(error), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("linear-teams", {
+    description: "List Linear teams and keys.",
+    handler: async (_args, ctx) => {
+      try {
+        const teams = await client.teams(ctx.signal);
+        pi.sendMessage({
+          content: formatTeams(teams),
+          customType: "linear-teams",
+          details: { teams },
+          display: true,
+        });
+      } catch (error) {
+        ctx.ui.notify(errorMessage(error), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("linear-states", {
+    description: "List Linear workflow states for a team: /linear-states ENG",
+    handler: async (args, ctx) => {
+      const team = args.trim();
+      if (!team) {
+        ctx.ui.notify("Usage: /linear-states TEAM_KEY", "error");
+        return;
+      }
+
+      try {
+        const states = await client.states(team, ctx.signal);
+        pi.sendMessage({
+          content: formatStates(team, states),
+          customType: "linear-states",
+          details: { states, team },
+          display: true,
+        });
+      } catch (error) {
+        ctx.ui.notify(errorMessage(error), "error");
+      }
+    },
+  });
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}