@vornrun/connector-linear 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import * as _vornrun_connector_sdk from '@vornrun/connector-sdk';
+
+/**
+ * Linear's GraphQL API, called directly.
+ *
+ * Linear publishes `@linear/sdk`, and this deliberately does not use it. The
+ * SDK is a generated client over the whole schema — megabytes of types for the
+ * four queries and three mutations below — and `npx` pays that download on
+ * every launch. The repo's rule is to prefer a maintained vendor client; this
+ * is the exception it allows, recorded here so nobody has to guess whether it
+ * was a decision.
+ *
+ * Every call takes `fetch` as an argument so tests never touch the network.
+ */
+type FetchLike = typeof fetch;
+
+interface LinearConnectorOptions {
+    version?: string;
+    /** Injected in tests, so nothing reaches the network. */
+    fetchImpl?: FetchLike;
+}
+declare function createLinearConnector(options?: LinearConnectorOptions): _vornrun_connector_sdk.Connector;
+
+declare const linearConnector: _vornrun_connector_sdk.Connector;
+
+export { type LinearConnectorOptions, createLinearConnector, linearConnector };

package/dist/index.js

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createRequire } from "module";
+
+// src/connector.ts
+import { defineConnector } from "@vornrun/connector-sdk";
+
+// src/client.ts
+var LINEAR_API = "https://api.linear.app/graphql";
+var TIMEOUT_MS = 15e3;
+var ISSUE_FIELDS = `
+  id
+  identifier
+  title
+  description
+  url
+  createdAt
+  updatedAt
+  state { name type }
+  labels { nodes { name } }
+  assignee { name }
+  team { key }
+`;
+async function linearGraphQL(options) {
+  const doFetch = options.fetchImpl ?? fetch;
+  const res = await doFetch(LINEAR_API, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: options.apiKey
+    },
+    body: JSON.stringify({ query: options.query, variables: options.variables ?? {} }),
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Linear API ${res.status}: ${body.slice(0, 200)}`);
+  }
+  const payload = await res.json();
+  if (payload.errors?.length) {
+    throw new Error(`Linear GraphQL error: ${payload.errors.map((e) => e.message).join("; ")}`);
+  }
+  if (!payload.data) throw new Error("Linear API returned no data");
+  return payload.data;
+}
+async function resolveIssueId(apiKey, identifier, fetchImpl) {
+  const data = await linearGraphQL({
+    apiKey,
+    ...fetchImpl && { fetchImpl },
+    query: `query IssueIdByIdentifier($identifier: String!) {
+       issues(filter: { identifier: { eq: $identifier } }, first: 1) { nodes { id } }
+     }`,
+    variables: { identifier }
+  });
+  return data.issues.nodes[0]?.id ?? null;
+}
+async function resolveIssueWithTeam(apiKey, identifier, fetchImpl) {
+  const data = await linearGraphQL({
+    apiKey,
+    ...fetchImpl && { fetchImpl },
+    query: `query IssueWithTeam($identifier: String!) {
+       issues(filter: { identifier: { eq: $identifier } }, first: 1) {
+         nodes { id team { id key } }
+       }
+     }`,
+    variables: { identifier }
+  });
+  const node = data.issues.nodes[0];
+  return node ? { id: node.id, teamId: node.team.id, teamKey: node.team.key } : null;
+}
+async function resolveTeamId(apiKey, teamKey, fetchImpl) {
+  const data = await linearGraphQL({
+    apiKey,
+    ...fetchImpl && { fetchImpl },
+    query: `query TeamIdByKey($key: String!) {
+       teams(filter: { key: { eq: $key } }, first: 1) { nodes { id } }
+     }`,
+    variables: { key: teamKey }
+  });
+  return data.teams.nodes[0]?.id ?? null;
+}
+async function resolveCompletedStateId(apiKey, teamId, fetchImpl) {
+  const data = await linearGraphQL({
+    apiKey,
+    ...fetchImpl && { fetchImpl },
+    query: `query CompletedStates($teamId: ID!) {
+       workflowStates(
+         filter: { team: { id: { eq: $teamId } }, type: { eq: "completed" } }
+         orderBy: position
+         first: 50
+       ) { nodes { id type position } }
+     }`,
+    variables: { teamId }
+  });
+  const nodes = data.workflowStates.nodes;
+  if (nodes.length === 0) return null;
+  return nodes.slice().sort((a, b) => a.position - b.position)[0].id;
+}
+
+// src/connector.ts
+var DEFAULT_LIMIT = 50;
+function required(config, key, env) {
+  const value = String(config[key] ?? "").trim();
+  if (!value) throw new Error(`${env} is required`);
+  return value;
+}
+function text(value) {
+  const trimmed = String(value ?? "").trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function issueToItem(issue) {
+  return {
+    externalId: issue.identifier,
+    url: issue.url,
+    title: issue.title,
+    description: issue.description ?? "",
+    status: issue.state.type,
+    labels: issue.labels.nodes.map((label) => label.name),
+    ...issue.assignee?.name && { assignee: issue.assignee.name },
+    updatedAt: issue.updatedAt,
+    // Everything else a workflow might template, under the key the SDK
+    // flattens into {{trigger.item.<key>}}.
+    data: {
+      createdAt: issue.createdAt,
+      stateName: issue.state.name,
+      teamKey: issue.team.key
+    }
+  };
+}
+function createLinearConnector(options = {}) {
+  const fetchImpl = options.fetchImpl;
+  async function fetchIssues(context) {
+    const config = context.config;
+    const apiKey = required(config, "apiKey", "LINEAR_API_KEY");
+    const teamKey = text(config.teamKey);
+    const stateType = text(config.stateType);
+    const limit = Number(config.limit ?? DEFAULT_LIMIT) || DEFAULT_LIMIT;
+    const filter = {};
+    if (teamKey) filter.team = { key: { eq: teamKey } };
+    if (stateType) filter.state = { type: { eq: stateType } };
+    if (context.since) filter.updatedAt = { gte: context.since };
+    const data = await linearGraphQL({
+      apiKey,
+      ...fetchImpl && { fetchImpl },
+      query: `
+        query ListIssues($filter: IssueFilter, $first: Int!) {
+          issues(filter: $filter, first: $first, orderBy: updatedAt) {
+            nodes { ${ISSUE_FIELDS} }
+          }
+        }
+      `,
+      variables: {
+        filter: Object.keys(filter).length > 0 ? filter : void 0,
+        first: limit
+      }
+    });
+    return data.issues.nodes.map(issueToItem);
+  }
+  return defineConnector({
+    id: "linear",
+    name: "Linear",
+    ...options.version && { version: options.version },
+    description: "Trigger workflows from Linear issues, and comment or close them from a step.",
+    // Linear's own mark.
+    icon: {
+      viewBox: "0 0 24 24",
+      paths: [
+        "M3.035 12.943c.207 1.98 1.07 3.904 2.587 5.421 1.517 1.517 3.441 2.38 5.42 2.587z",
+        "M3 11.494L12.492 20.986c.806-.045 1.606-.198 2.378-.459L3.459 9.115A9.6 9.6 0 003 11.494z",
+        "M3.867 8.11l12.009 12.009a9.6 9.6 0 001.773-1.123L4.99 6.337a9.6 9.6 0 00-1.123 1.773z",
+        "M5.663 5.595c3.518-3.474 9.186-3.46 12.687.04 3.501 3.501 3.515 9.169.041 12.687z"
+      ]
+    },
+    config: [
+      {
+        key: "apiKey",
+        env: "LINEAR_API_KEY",
+        label: "Linear API key",
+        // Stored encrypted by Vorn and never printed by the CLI.
+        secret: true,
+        required: true,
+        description: "Create a personal API key at linear.app/settings/api."
+      },
+      {
+        key: "teamKey",
+        env: "LINEAR_TEAM_KEY",
+        label: "Team key",
+        description: "Upper-case key such as ENG. Leave blank for every team you can see."
+      },
+      {
+        key: "stateType",
+        env: "LINEAR_STATE_TYPE",
+        label: "State",
+        description: "One of backlog, unstarted, started, completed, canceled. Blank for all states."
+      },
+      {
+        key: "limit",
+        env: "LINEAR_LIMIT",
+        label: "Maximum per poll",
+        default: String(DEFAULT_LIMIT)
+      }
+    ],
+    triggers: [
+      {
+        type: "issueCreated",
+        label: "An issue is created or changed",
+        description: "Fires for each issue the query returns that Vorn has not seen at this time.",
+        // Issues carry updatedAt, so the watermark advances on it rather than
+        // re-reading everything the filter still matches.
+        dedupe: "timestamp",
+        // What each Linear state type should become as a Vorn task. Without
+        // these every issue imports as `todo`, including ones closed a year
+        // ago.
+        statusMapping: [
+          { upstream: "backlog", suggestedLocal: "todo" },
+          { upstream: "unstarted", suggestedLocal: "todo" },
+          { upstream: "started", suggestedLocal: "in_progress" },
+          { upstream: "completed", suggestedLocal: "done" },
+          { upstream: "canceled", suggestedLocal: "cancelled" }
+        ],
+        defaultWorkflow: { name: "Linear: issues", defaultCronFromMinutes: 5 },
+        fetch: fetchIssues
+      }
+    ],
+    actions: [
+      {
+        type: "commentOnIssue",
+        label: "Comment on an issue",
+        description: "Post a comment on a Linear issue.",
+        // Two identical calls make two comments.
+        idempotent: false,
+        inputs: [
+          { key: "identifier", label: "Issue", required: true, description: "e.g. ENG-123" },
+          { key: "body", label: "Comment", required: true }
+        ],
+        outputs: [{ key: "url", description: "Where to read the comment" }],
+        async run(args, { config }) {
+          const apiKey = required(config, "apiKey", "LINEAR_API_KEY");
+          const identifier = text(args.identifier);
+          const body = text(args.body);
+          if (!identifier) throw new Error("identifier is required (e.g. ENG-123)");
+          if (!body) throw new Error("body is required");
+          const issueId = await resolveIssueId(apiKey, identifier, fetchImpl);
+          if (!issueId) throw new Error(`Issue ${identifier} not found`);
+          const data = await linearGraphQL({
+            apiKey,
+            ...fetchImpl && { fetchImpl },
+            query: `mutation CreateComment($input: CommentCreateInput!) {
+               commentCreate(input: $input) { success comment { id url } }
+             }`,
+            variables: { input: { issueId, body } }
+          });
+          if (!data.commentCreate.success) throw new Error("Linear refused to create the comment");
+          return { url: data.commentCreate.comment.url };
+        }
+      },
+      {
+        type: "createIssue",
+        label: "Create an issue",
+        description: "Open a new Linear issue and return its identifier and url.",
+        idempotent: false,
+        inputs: [
+          { key: "title", label: "Title", required: true },
+          { key: "description", label: "Description" },
+          { key: "teamKey", label: "Team key", description: "Defaults to the connection\u2019s team." }
+        ],
+        outputs: [
+          { key: "identifier", description: "e.g. ENG-123" },
+          { key: "url", description: "Where to open it" }
+        ],
+        async run(args, { config }) {
+          const cfg = config;
+          const apiKey = required(cfg, "apiKey", "LINEAR_API_KEY");
+          const title = text(args.title);
+          if (!title) throw new Error("title is required");
+          const teamKey = text(args.teamKey) ?? text(cfg.teamKey);
+          if (!teamKey) {
+            throw new Error("teamKey is required: set one on the connection or pass it here.");
+          }
+          const teamId = await resolveTeamId(apiKey, teamKey, fetchImpl);
+          if (!teamId) throw new Error(`Team ${teamKey} not found`);
+          const input = { teamId, title };
+          const description = text(args.description);
+          if (description) input.description = description;
+          const data = await linearGraphQL({
+            apiKey,
+            ...fetchImpl && { fetchImpl },
+            query: `mutation CreateIssue($input: IssueCreateInput!) {
+               issueCreate(input: $input) { success issue { id identifier url } }
+             }`,
+            variables: { input }
+          });
+          if (!data.issueCreate.success) throw new Error("Linear refused to create the issue");
+          return {
+            identifier: data.issueCreate.issue.identifier,
+            url: data.issueCreate.issue.url
+          };
+        }
+      },
+      {
+        type: "closeIssue",
+        label: "Close an issue",
+        description: "Move an issue to the first completed state its team defines.",
+        // Closing an issue that is already closed lands it in the same place.
+        idempotent: true,
+        inputs: [
+          { key: "identifier", label: "Issue", required: true, description: "e.g. ENG-123" }
+        ],
+        outputs: [{ key: "state", description: "The state it now holds" }],
+        async run(args, { config }) {
+          const apiKey = required(config, "apiKey", "LINEAR_API_KEY");
+          const identifier = text(args.identifier);
+          if (!identifier) throw new Error("identifier is required (e.g. ENG-123)");
+          const issue = await resolveIssueWithTeam(apiKey, identifier, fetchImpl);
+          if (!issue) throw new Error(`Issue ${identifier} not found`);
+          const stateId = await resolveCompletedStateId(apiKey, issue.teamId, fetchImpl);
+          if (!stateId) {
+            throw new Error(`Team ${issue.teamKey} has no completed state to move it to.`);
+          }
+          const data = await linearGraphQL({
+            apiKey,
+            ...fetchImpl && { fetchImpl },
+            query: `mutation CloseIssue($id: String!, $input: IssueUpdateInput!) {
+               issueUpdate(id: $id, input: $input) { success issue { id state { name } } }
+             }`,
+            variables: { id: issue.id, input: { stateId } }
+          });
+          if (!data.issueUpdate.success) throw new Error("Linear refused to close the issue");
+          return { state: data.issueUpdate.issue.state.name };
+        }
+      }
+    ]
+  });
+}
+
+// src/entry.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { serveConnector } from "@vornrun/connector-sdk";
+function isEntryPoint(moduleUrl, entry = process.argv[1]) {
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+function serveIfEntryPoint(connector, moduleUrl, serve = serveConnector) {
+  if (!isEntryPoint(moduleUrl)) return false;
+  void serve(connector);
+  return true;
+}
+
+// src/index.ts
+var { version } = createRequire(import.meta.url)("../package.json");
+var linearConnector = createLinearConnector({ version });
+serveIfEntryPoint(linearConnector, import.meta.url);
+export {
+  createLinearConnector,
+  linearConnector
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@vornrun/connector-linear",
+  "version": "0.1.0",
+  "description": "Trigger workflows from Linear issues.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vorn-run/connectors.git",
+    "directory": "packages/ado"
+  },
+  "bin": {
+    "vorn-connector-linear": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --target node22 --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@vornrun/connector-sdk": "^0.5.7",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "vorn": {
+    "category": "Development",
+    "keywords": [
+      "linear",
+      "issues",
+      "tickets",
+      "engineering",
+      "backlog"
+    ],
+    "auth": "Uses a Linear personal API key, created at linear.app/settings/api."
+  }
+}