@h-rig/linear-plugin 0.0.6-alpha.100

package/dist/src/index.js

@@ -0,0 +1,492 @@
+// @bun
+// packages/linear-plugin/src/index.ts
+import { definePlugin } from "@rig/core";
+
+// packages/linear-plugin/src/linear-issues-source.ts
+var ISSUE_FIELDS = `
+      id
+      identifier
+      title
+      description
+      priority
+      priorityLabel
+      url
+      state { id name type }
+      labels { nodes { name } }
+      assignee { name email }`;
+var LIST_ISSUES_QUERY = `query RigListIssues($filter: IssueFilter, $first: Int!, $after: String) {
+  issues(filter: $filter, first: $first, after: $after) {
+    pageInfo { hasNextPage endCursor }
+    nodes {${ISSUE_FIELDS}
+    }
+  }
+}`;
+var GET_ISSUE_QUERY = `query RigGetIssue($id: String!) {
+  issue(id: $id) {${ISSUE_FIELDS}
+  }
+}`;
+var RESOLVE_ISSUE_QUERY = `query RigResolveIssue($id: String!) {
+  issue(id: $id) { id }
+}`;
+var ISSUE_DESCRIPTION_QUERY = `query RigIssueDescription($id: String!) {
+  issue(id: $id) { description }
+}`;
+var TEAM_STATES_QUERY = `query RigTeamStates($teamKey: String!) {
+  teams(filter: { key: { eq: $teamKey } }, first: 1) {
+    nodes {
+      id
+      key
+      states { nodes { id name type position } }
+    }
+  }
+}`;
+var ISSUE_UPDATE_MUTATION = `mutation RigIssueUpdate($id: String!, $input: IssueUpdateInput!) {
+  issueUpdate(id: $id, input: $input) { success }
+}`;
+var COMMENT_CREATE_MUTATION = `mutation RigCommentCreate($input: CommentCreateInput!) {
+  commentCreate(input: $input) { success }
+}`;
+function rigStatusForLinearStateType(stateType) {
+  switch (stateType) {
+    case "triage":
+    case "backlog":
+    case "unstarted":
+      return "ready";
+    case "started":
+      return "in_progress";
+    case "completed":
+      return "completed";
+    case "canceled":
+      return "cancelled";
+    default:
+      return "open";
+  }
+}
+function linearStateTypeForRigStatus(status) {
+  switch (status) {
+    case "ready":
+      return "unstarted";
+    case "in_progress":
+    case "under_review":
+    case "ci_fixing":
+    case "merging":
+      return "started";
+    case "closed":
+    case "completed":
+      return "completed";
+    case "cancelled":
+      return "canceled";
+    case "blocked":
+    case "failed":
+    case "needs_attention":
+    case "open":
+      return null;
+    default:
+      return null;
+  }
+}
+var RIG_METADATA_START = "<!-- rig:metadata:start -->";
+var RIG_METADATA_END = "<!-- rig:metadata:end -->";
+function yamlScalar(value) {
+  if (Array.isArray(value)) {
+    return value.length === 0 ? "[]" : `
+${value.map((entry) => `  - ${String(entry)}`).join(`
+`)}`;
+  }
+  if (value && typeof value === "object")
+    return JSON.stringify(value);
+  return String(value);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function updateRigOwnedMetadataBlock(body, metadata) {
+  const rendered = [
+    RIG_METADATA_START,
+    ...Object.entries(metadata).map(([key, value]) => Array.isArray(value) ? `${key}:${yamlScalar(value)}` : `${key}: ${yamlScalar(value)}`),
+    RIG_METADATA_END
+  ].join(`
+`);
+  const pattern = new RegExp(`${escapeRegExp(RIG_METADATA_START)}\\s*[\\s\\S]*?\\s*${escapeRegExp(RIG_METADATA_END)}`);
+  if (pattern.test(body))
+    return body.replace(pattern, rendered);
+  return body.trim().length > 0 ? `${body.trimEnd()}
+
+${rendered}
+` : `${rendered}
+`;
+}
+function labelNamesFor(issue) {
+  return (issue.labels?.nodes ?? []).map((label) => label.name);
+}
+function issueToTask(issue) {
+  const labelNames = labelNamesFor(issue);
+  const scope = labelNames.filter((l) => l.startsWith("scope:")).map((l) => l.slice("scope:".length));
+  const roleLabel = labelNames.find((l) => l.startsWith("role:"));
+  const validators = labelNames.filter((l) => l.startsWith("validator:")).map((l) => l.slice("validator:".length));
+  const description = issue.description ?? "";
+  return {
+    id: issue.identifier,
+    deps: [],
+    status: rigStatusForLinearStateType(issue.state?.type),
+    title: issue.title,
+    body: description,
+    description,
+    ...scope.length > 0 ? { scope } : {},
+    ...roleLabel ? { role: roleLabel.slice("role:".length) } : {},
+    ...validators.length > 0 ? { validators } : {},
+    ...issue.priority !== null && issue.priority !== undefined ? { priority: issue.priority } : {},
+    ...issue.priorityLabel ? { priorityLabel: issue.priorityLabel } : {},
+    ...issue.url ? { url: issue.url } : {},
+    labels: labelNames,
+    externalRef: `linear:${issue.identifier}`,
+    sourceIssueId: issue.identifier,
+    linearIssueId: issue.id,
+    ...issue.state ? { stateName: issue.state.name, stateType: issue.state.type } : {},
+    raw: issue
+  };
+}
+function buildIssueFilter(opts) {
+  const filter = { team: { key: { eq: opts.teamKey } } };
+  if (opts.states && opts.states.length > 0) {
+    filter.state = { name: { in: [...opts.states] } };
+  }
+  const assignee = opts.assignee?.trim();
+  if (assignee) {
+    filter.assignee = assignee.includes("@") ? { email: { eq: assignee } } : { displayName: { eq: assignee } };
+  }
+  if (opts.labels && opts.labels.length > 0) {
+    filter.and = opts.labels.map((name) => ({ labels: { some: { name: { eq: name } } } }));
+  }
+  return filter;
+}
+var DEFAULT_ENDPOINT = "https://api.linear.app/graphql";
+var DEFAULT_PAGE_SIZE = 50;
+var DEFAULT_LIST_LIMIT = 1000;
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function truncateForError(text) {
+  const clean = text.replace(/\s+/g, " ").trim();
+  return clean.length > 300 ? `${clean.slice(0, 300)}\u2026` : clean;
+}
+function isAuthErrorPayload(status, errors) {
+  if (status === 401)
+    return "HTTP 401";
+  for (const error of errors ?? []) {
+    const code = error.extensions?.code ?? "";
+    if (code === "AUTHENTICATION_ERROR" || /authentication/i.test(error.message ?? "")) {
+      return error.message ?? code;
+    }
+  }
+  return null;
+}
+function createGraphQLClient(opts) {
+  const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+  const transport = opts.transport ?? fetch;
+  return {
+    async request(query, variables) {
+      const apiKey = (opts.apiKey ?? process.env.LINEAR_API_KEY)?.trim();
+      if (!apiKey) {
+        throw new Error("Linear task source: no API key configured. Pass apiKey in plugin options or set the LINEAR_API_KEY environment variable.");
+      }
+      const authorization = apiKey.startsWith("lin_oauth_") ? `Bearer ${apiKey}` : apiKey;
+      let response;
+      try {
+        response = await transport(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: authorization
+          },
+          body: JSON.stringify({ query, variables })
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Linear API request failed (network error): ${message}`, { cause: error });
+      }
+      const text = await response.text();
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = undefined;
+      }
+      const authError = isAuthErrorPayload(response.status, parsed?.errors);
+      if (authError) {
+        throw new Error(`Linear API authentication failed (${authError}). Check that the configured API key (options.apiKey / LINEAR_API_KEY) is a valid Linear key with access to team "${opts.teamKey}".`);
+      }
+      if (!response.ok) {
+        throw new Error(`Linear API request failed (HTTP ${response.status}): ${truncateForError(text)}`);
+      }
+      if (parsed?.errors && parsed.errors.length > 0) {
+        const messages = parsed.errors.map((e) => e.message ?? "unknown error").join("; ");
+        throw new Error(`Linear GraphQL error: ${messages}`);
+      }
+      if (!parsed || parsed.data === undefined || parsed.data === null) {
+        throw new Error(`Linear API returned no data: ${truncateForError(text)}`);
+      }
+      return parsed.data;
+    }
+  };
+}
+function createLinearIssuesTaskSource(opts) {
+  if (!opts.teamKey?.trim()) {
+    throw new Error("createLinearIssuesTaskSource: teamKey is required");
+  }
+  const teamKey = opts.teamKey.trim();
+  const client = createGraphQLClient(opts);
+  const pageSize = Math.min(250, Math.max(1, Math.trunc(opts.pageSize ?? DEFAULT_PAGE_SIZE)));
+  const listLimit = Math.max(1, Math.trunc(opts.listLimit ?? DEFAULT_LIST_LIMIT));
+  let cachedStates = null;
+  const fetchTeamStates = async () => {
+    if (cachedStates)
+      return cachedStates;
+    const data = await client.request(TEAM_STATES_QUERY, { teamKey });
+    const team = data.teams.nodes[0];
+    if (!team) {
+      throw new Error(`Linear team not found for key "${teamKey}" \u2014 check taskSource.options.teamKey.`);
+    }
+    cachedStates = team.states.nodes;
+    return cachedStates;
+  };
+  const resolveStateId = async (stateType) => {
+    const states = await fetchTeamStates();
+    const candidates = states.filter((s) => s.type === stateType).toSorted((a, b) => (a.position ?? 0) - (b.position ?? 0));
+    const target = candidates[0];
+    if (!target) {
+      throw new Error(`Linear team "${teamKey}" has no workflow state of type "${stateType}" \u2014 cannot map this Rig status to a Linear state.`);
+    }
+    return target.id;
+  };
+  const resolveIssueUuid = async (taskId) => {
+    if (UUID_PATTERN.test(taskId))
+      return taskId;
+    const data = await client.request(RESOLVE_ISSUE_QUERY, { id: taskId });
+    if (!data.issue) {
+      throw new Error(`Linear issue not found: ${taskId}`);
+    }
+    return data.issue.id;
+  };
+  const fetchDescription = async (issueUuid) => {
+    const data = await client.request(ISSUE_DESCRIPTION_QUERY, { id: issueUuid });
+    return data.issue?.description ?? "";
+  };
+  const applyIssueUpdate = async (taskId, update) => {
+    const issueUuid = await resolveIssueUuid(taskId);
+    const input = {};
+    if (update.status) {
+      const stateType = linearStateTypeForRigStatus(update.status);
+      if (stateType)
+        input.stateId = await resolveStateId(stateType);
+    }
+    if (update.title?.trim())
+      input.title = update.title.trim();
+    const nextBody = update.metadata ? updateRigOwnedMetadataBlock(update.body ?? await fetchDescription(issueUuid), update.metadata) : update.body;
+    if (nextBody !== undefined)
+      input.description = nextBody;
+    if (Object.keys(input).length > 0) {
+      await client.request(ISSUE_UPDATE_MUTATION, {
+        id: issueUuid,
+        input
+      });
+    }
+    if (update.comment?.trim()) {
+      await client.request(COMMENT_CREATE_MUTATION, {
+        input: { issueId: issueUuid, body: update.comment }
+      });
+    }
+  };
+  const notifyTaskChanged = (id, status) => {
+    opts.onTaskChanged?.({ teamKey, id, ...status ? { status } : {}, reason: "linear-issue-updated" });
+  };
+  return {
+    id: "linear:issues",
+    kind: "linear",
+    async list() {
+      const filter = buildIssueFilter({ ...opts, teamKey });
+      const out = [];
+      let after = null;
+      for (;; ) {
+        const data = await client.request(LIST_ISSUES_QUERY, {
+          filter,
+          first: pageSize,
+          after
+        });
+        out.push(...data.issues.nodes.map(issueToTask));
+        if (out.length > listLimit) {
+          throw new Error(`Linear issue list for team ${teamKey} exceeded the configured limit (${listLimit}); refusing to silently truncate matching issues. Increase taskSource.options.listLimit or narrow states/labels/assignee.`);
+        }
+        if (!data.issues.pageInfo.hasNextPage)
+          break;
+        after = data.issues.pageInfo.endCursor ?? null;
+        if (!after)
+          break;
+      }
+      return out;
+    },
+    async get(id) {
+      try {
+        const data = await client.request(GET_ISSUE_QUERY, { id });
+        return data.issue ? issueToTask(data.issue) : undefined;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/authentication|API key/i.test(message))
+          throw error;
+        if (/not found|entity not found/i.test(message))
+          return;
+        throw error;
+      }
+    },
+    async updateStatus(id, status) {
+      const stateType = linearStateTypeForRigStatus(status);
+      if (stateType) {
+        const issueUuid = await resolveIssueUuid(id);
+        const stateId = await resolveStateId(stateType);
+        await client.request(ISSUE_UPDATE_MUTATION, {
+          id: issueUuid,
+          input: { stateId }
+        });
+      }
+      notifyTaskChanged(id, status);
+    },
+    async updateTask(id, update) {
+      await applyIssueUpdate(id, update);
+      notifyTaskChanged(id, update.status);
+    }
+  };
+}
+// packages/linear-plugin/src/fixture-transport.ts
+var HTTP_FAILURE = Symbol("linear-fixture-http-failure");
+var GRAPHQL_ERRORS = Symbol("linear-fixture-graphql-errors");
+function httpFailure(status, body) {
+  return { [HTTP_FAILURE]: true, status, body };
+}
+function graphqlErrors(errors) {
+  return { [GRAPHQL_ERRORS]: true, errors };
+}
+function isHttpFailure(value) {
+  return typeof value === "object" && value !== null && HTTP_FAILURE in value;
+}
+function isGraphQLErrors(value) {
+  return typeof value === "object" && value !== null && GRAPHQL_ERRORS in value;
+}
+function jsonResponse(status, body) {
+  return { ok: status >= 200 && status < 300, status, text: async () => body };
+}
+function createFixtureTransport(routes) {
+  const calls = [];
+  const transport = async (url, init) => {
+    const body = JSON.parse(init.body);
+    const operation = /(?:query|mutation)\s+([A-Za-z0-9_]+)/.exec(body.query)?.[1] ?? "<anonymous>";
+    const call = {
+      url,
+      authorization: init.headers["Authorization"],
+      operation,
+      query: body.query,
+      variables: body.variables ?? {}
+    };
+    calls.push(call);
+    const route = routes[operation];
+    if (!route) {
+      throw new Error(`createFixtureTransport: no fixture route for operation "${operation}"`);
+    }
+    const result = route(call.variables, call);
+    if (isHttpFailure(result)) {
+      return jsonResponse(result.status, result.body);
+    }
+    if (isGraphQLErrors(result)) {
+      return jsonResponse(200, JSON.stringify({ errors: result.errors }));
+    }
+    return jsonResponse(200, JSON.stringify({ data: result }));
+  };
+  return {
+    transport,
+    calls,
+    callsFor: (operation) => calls.filter((c) => c.operation === operation)
+  };
+}
+
+// packages/linear-plugin/src/index.ts
+var TASK_SOURCE_ID = "linear:issues";
+var TASK_SOURCE_KIND = "linear";
+var TASK_SOURCE_DESCRIPTION = "Linear issues via the Linear GraphQL API";
+function optionString(config, field) {
+  const value = config.options?.[field];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function optionStringArray(config, field) {
+  const value = config.options?.[field];
+  if (!Array.isArray(value))
+    return;
+  const strings = value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+  return strings.length > 0 ? strings : undefined;
+}
+function optionNumber(config, field) {
+  const value = config.options?.[field];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function linearPlugin(opts = {}) {
+  return definePlugin({
+    name: "rig-linear",
+    version: "0.1.0",
+    contributes: {
+      taskSources: [
+        {
+          id: TASK_SOURCE_ID,
+          kind: TASK_SOURCE_KIND,
+          description: TASK_SOURCE_DESCRIPTION
+        }
+      ]
+    }
+  }, {
+    taskSources: [
+      {
+        id: TASK_SOURCE_ID,
+        kind: TASK_SOURCE_KIND,
+        description: TASK_SOURCE_DESCRIPTION,
+        factory(config) {
+          const teamKey = optionString(config, "teamKey");
+          if (!teamKey) {
+            throw new Error('task source linear: options.teamKey is required \u2014 e.g. taskSource: { kind: "linear", options: { teamKey: "ENG" } }');
+          }
+          const options = { teamKey };
+          if (opts.apiKey)
+            options.apiKey = opts.apiKey;
+          if (opts.endpoint)
+            options.endpoint = opts.endpoint;
+          if (opts.transport)
+            options.transport = opts.transport;
+          if (opts.onTaskChanged)
+            options.onTaskChanged = opts.onTaskChanged;
+          const states = optionStringArray(config, "states");
+          if (states)
+            options.states = states;
+          const assignee = optionString(config, "assignee");
+          if (assignee)
+            options.assignee = assignee;
+          const labels = optionStringArray(config, "labels") ?? (config.labels && config.labels.length > 0 ? [...config.labels] : undefined);
+          if (labels)
+            options.labels = labels;
+          const pageSize = optionNumber(config, "pageSize");
+          if (pageSize !== undefined)
+            options.pageSize = pageSize;
+          const listLimit = optionNumber(config, "listLimit");
+          if (listLimit !== undefined)
+            options.listLimit = listLimit;
+          return createLinearIssuesTaskSource(options);
+        }
+      }
+    ]
+  });
+}
+export {
+  updateRigOwnedMetadataBlock,
+  rigStatusForLinearStateType,
+  linearStateTypeForRigStatus,
+  httpFailure,
+  graphqlErrors,
+  linearPlugin as default,
+  createLinearIssuesTaskSource,
+  createFixtureTransport,
+  RIG_METADATA_START,
+  RIG_METADATA_END
+};

package/dist/src/linear-issues-source.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Linear issues task source — the canonical external-HTTP-API adapter.
+ *
+ * Everything goes through one GraphQL endpoint (`https://api.linear.app/graphql`)
+ * via an injectable fetch-shaped transport, so the entire adapter is testable
+ * from fixtures with zero live API calls. See the package README for the
+ * walk-through; this file is deliberately self-contained (no SDK dependency).
+ */
+import type { RegisteredTaskSource, TaskRecord, TaskSourceUpdate } from "@rig/contracts";
+/** The exact request shape the adapter sends. */
+export interface LinearTransportRequest {
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+}
+/** The minimal response surface the adapter reads. `Response` satisfies it. */
+export interface LinearTransportResponse {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}
+/**
+ * A fetch-shaped function. Global `fetch` is assignable as-is; tests inject a
+ * fixture-driven fake (see `createFixtureTransport` in `fixture-transport.ts`).
+ */
+export type LinearTransport = (url: string, init: LinearTransportRequest) => Promise<LinearTransportResponse>;
+export interface LinearIssuesOptions {
+    /** Linear team key (the "ENG" in ENG-123). Issues are listed for this team. */
+    teamKey: string;
+    /**
+     * Linear API key. Defaults to `process.env.LINEAR_API_KEY`, resolved at
+     * request time. Personal API keys (`lin_api_…`) are sent raw in the
+     * `Authorization` header; OAuth tokens (`lin_oauth_…`) get a `Bearer` prefix.
+     */
+    apiKey?: string;
+    /** Filter: workflow state names (e.g. `["Todo", "In Progress"]`). */
+    states?: readonly string[];
+    /** Filter: assignee email (anything containing "@") or display name. */
+    assignee?: string;
+    /** Filter: label names. An issue must carry every listed label (AND). */
+    labels?: readonly string[];
+    /** GraphQL endpoint override. Defaults to the public Linear API. */
+    endpoint?: string;
+    /** fetch-shaped transport. Defaults to global `fetch`; tests inject a fake. */
+    transport?: LinearTransport;
+    /** Issues per GraphQL page (Linear caps pages at 250). Defaults to 50. */
+    pageSize?: number;
+    /** Maximum issue-list rows before Rig fails loudly instead of silently truncating. Defaults to 1,000. */
+    listLimit?: number;
+    /** Notify the host that issue-backed task state changed and snapshots should refresh. */
+    onTaskChanged?: (event: {
+        teamKey: string;
+        id: string;
+        status?: TaskRecord["status"];
+        reason: "linear-issue-updated";
+    }) => void;
+}
+/**
+ * Linear workflow-state *type* → Rig task status.
+ *   triage / backlog / unstarted → ready
+ *   started                      → in_progress
+ *   completed                    → completed
+ *   canceled                     → cancelled
+ * Unknown types fall back to "open" rather than failing the whole list.
+ */
+export declare function rigStatusForLinearStateType(stateType: string | undefined): TaskRecord["status"];
+/**
+ * Rig task status → Linear workflow-state type for lifecycle writeback.
+ * Returns null when Linear has no workflow equivalent (e.g. "blocked") — the
+ * adapter then leaves the workflow state untouched and relies on comments.
+ */
+export declare function linearStateTypeForRigStatus(status: TaskRecord["status"]): "unstarted" | "started" | "completed" | "canceled" | null;
+export declare const RIG_METADATA_START = "<!-- rig:metadata:start -->";
+export declare const RIG_METADATA_END = "<!-- rig:metadata:end -->";
+/** Insert or replace the Rig-owned metadata block in an issue description. */
+export declare function updateRigOwnedMetadataBlock(body: string, metadata: Record<string, unknown>): string;
+export interface LinearIssuesTaskSource extends RegisteredTaskSource {
+    get(id: string): Promise<TaskRecord | undefined>;
+    updateStatus(id: string, status: TaskRecord["status"]): Promise<void>;
+    updateTask(id: string, update: TaskSourceUpdate): Promise<void>;
+}
+export declare function createLinearIssuesTaskSource(opts: LinearIssuesOptions): LinearIssuesTaskSource;