@sentry/junior-linear 0.119.0 → 0.120.0

package/README.md

@@ -8,17 +8,18 @@ Install it alongside `@sentry/junior`:
 pnpm add @sentry/junior @sentry/junior-linear
 ```
 
-Then add the package name to the plugin set exported from `plugins.ts`:
+Then add the plugin to the set exported from `plugins.ts`:
 
 ```ts title="plugins.ts"
 import { defineJuniorPlugins } from "@sentry/junior";
+import { linearPlugin } from "@sentry/junior-linear";
 
-export const plugins = defineJuniorPlugins(["@sentry/junior-linear"]);
+export const plugins = defineJuniorPlugins([linearPlugin()]);
 ```
 
 This package does not require a shared `LINEAR_API_KEY` or a custom OAuth app for the default setup. Each user connects their own Linear account the first time Junior calls a Linear MCP tool. Junior sends the authorization link privately and resumes the same Slack thread automatically after the user authorizes.
 
-The package is designed for ticket-centric work: finding issues, creating issues, updating fields, adding comments, and moving work through the normal Linear workflow without leaving Slack.
+Issue creation uses a Junior-owned tool backed by Linear's hosted MCP connection. This lets Junior prevent duplicate retries and link created issues to the conversation while keeping Linear's existing OAuth flow. Other Linear operations continue to use the hosted MCP tools.
 
 Optional: set channel defaults when a Slack thread usually routes work to the same Linear destination:
 

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { linearPlugin } from "./plugin.js";

package/dist/index.js

@@ -0,0 +1,244 @@
+// src/plugin.ts
+import {
+  defineJuniorPlugin
+} from "@sentry/junior-plugin-api";
+
+// src/tools/create-issue.ts
+import {
+  definePluginTool,
+  PluginToolInputError,
+  pluginToolResultSchema
+} from "@sentry/junior-plugin-api";
+import { z } from "zod";
+var CREATE_ISSUE_STATE_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
+var CREATE_ISSUE_LOCK_TTL_MS = 6e4;
+var inputSchema = z.object({
+  team: z.string().trim().min(1).describe("Linear team name or identifier."),
+  title: z.string().trim().min(1).max(60).describe("Issue title."),
+  description: z.string().describe("Issue description.").optional(),
+  priority: z.enum(["low", "medium", "high", "urgent"]).describe("Linear priority.").optional(),
+  project: z.string().trim().min(1).describe("Linear project name or identifier.").optional()
+}).strict();
+var issueSchema = z.object({
+  id: z.string().optional(),
+  identifier: z.string().optional(),
+  title: z.string().optional(),
+  url: z.string().url().optional()
+}).strict();
+var outputSchema = pluginToolResultSchema.extend({
+  ok: z.literal(true),
+  status: z.literal("success"),
+  target: z.literal("createIssue"),
+  data: z.object({
+    issue: issueSchema.nullable(),
+    providerText: z.string()
+  }),
+  issue: issueSchema.nullable(),
+  providerText: z.string()
+});
+var completedStateSchema = z.object({
+  createdAtMs: z.number(),
+  issue: issueSchema.nullable(),
+  providerText: z.string(),
+  status: z.literal("completed")
+}).strict();
+var pendingStateSchema = z.object({
+  createdAtMs: z.number(),
+  status: z.literal("pending")
+}).strict();
+var stateSchema = z.union([completedStateSchema, pendingStateSchema]);
+function parseState(value) {
+  const parsed = stateSchema.safeParse(value);
+  return parsed.success ? parsed.data : void 0;
+}
+function collectObjects(value, objects) {
+  if (!value || typeof value !== "object") {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectObjects(item, objects);
+    return;
+  }
+  const record = value;
+  objects.push(record);
+  for (const item of Object.values(record)) collectObjects(item, objects);
+}
+function stringField(objects, field) {
+  for (const object of objects) {
+    const value = object[field];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return void 0;
+}
+function providerText(result) {
+  return result.content.filter(
+    (part) => part.type === "text"
+  ).map((part) => part.text).join("\n\n").trim();
+}
+function parseJsonText(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function extractIssue(result) {
+  const text = providerText(result);
+  const objects = [];
+  collectObjects(result.structuredContent, objects);
+  collectObjects(parseJsonText(text), objects);
+  const urlMatch = text.match(
+    /https:\/\/linear\.app\/[^\s<>)"']+\/issue\/([A-Z][A-Z0-9]*-\d+)[^\s<>)"']*/i
+  );
+  const identifierMatch = text.match(/\b[A-Z][A-Z0-9]*-\d+\b/);
+  const issue = {
+    id: stringField(objects, "id"),
+    identifier: stringField(objects, "identifier") ?? urlMatch?.[1]?.toUpperCase() ?? identifierMatch?.[0],
+    title: stringField(objects, "title"),
+    url: stringField(objects, "url") ?? urlMatch?.[0]
+  };
+  const parsed = issueSchema.safeParse(
+    Object.fromEntries(
+      Object.entries(issue).filter((entry) => entry[1] !== void 0)
+    )
+  );
+  if (!parsed.success || Object.keys(parsed.data).length === 0) {
+    return null;
+  }
+  return parsed.data;
+}
+function toolResult(issue, text) {
+  const data = { issue, providerText: text };
+  return {
+    ok: true,
+    status: "success",
+    target: "createIssue",
+    data,
+    ...data
+  };
+}
+async function annotateIssue(ctx, issue) {
+  if (!issue?.identifier || !issue.url) {
+    return;
+  }
+  await ctx.annotations?.upsert({
+    kind: "resource_link",
+    key: issue.identifier.toUpperCase(),
+    label: issue.identifier.toUpperCase(),
+    url: issue.url,
+    status: "open"
+  });
+}
+function required(value, name) {
+  if (!value?.trim()) throw new PluginToolInputError(`${name} is required`);
+  return value.trim();
+}
+function createLinearIssueTool(ctx) {
+  return definePluginTool({
+    description: "Create a Linear issue through Linear's hosted MCP provider and link the created issue to the current Junior conversation.",
+    inputSchema,
+    outputSchema,
+    annotations: {
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+      readOnlyHint: false,
+      title: "Create Linear issue"
+    },
+    describeProposal(input) {
+      return `Create a Linear issue in ${input.team}: ${input.title}`;
+    },
+    async execute(input, options) {
+      const mcp = ctx.mcp;
+      if (!mcp) {
+        throw new Error("Linear MCP provider is unavailable.");
+      }
+      const conversationId = required(ctx.conversationId, "conversationId");
+      const toolCallId = required(options.toolCallId, "toolCallId");
+      if (await mcp.prepare() === "authorization_pending") {
+        return toolResult(null, "Authorization pending.");
+      }
+      const key = `createIssue:${conversationId}:${toolCallId}`;
+      return await ctx.state.withLock(
+        `${key}:lock`,
+        CREATE_ISSUE_LOCK_TTL_MS,
+        async () => {
+          const state = parseState(await ctx.state.get(key));
+          if (state?.status === "completed") {
+            await annotateIssue(ctx, state.issue);
+            return toolResult(state.issue, state.providerText);
+          }
+          if (state?.status === "pending") {
+            throw new Error(
+              "Linear issue creation for this tool call has an uncertain pending result; refusing to create a duplicate issue."
+            );
+          }
+          await ctx.state.set(
+            key,
+            { status: "pending", createdAtMs: Date.now() },
+            CREATE_ISSUE_STATE_TTL_MS
+          );
+          const result = await mcp.callTool({
+            name: "create_issue",
+            arguments: input,
+            toolCallId
+          });
+          if (result.status === "authorization_pending") {
+            await ctx.state.delete(key);
+            return toolResult(null, "Authorization pending.");
+          }
+          if (result.status === "error") {
+            await ctx.state.delete(key);
+            throw new Error(result.message);
+          }
+          const text = providerText(result);
+          const issue = extractIssue(result);
+          const completedState = {
+            status: "completed",
+            createdAtMs: Date.now(),
+            issue,
+            providerText: text
+          };
+          try {
+            await ctx.state.set(key, completedState, CREATE_ISSUE_STATE_TTL_MS);
+          } catch (error) {
+            throw new Error(
+              "Linear issue was created, but Junior could not persist the completed issue state.",
+              { cause: error }
+            );
+          }
+          await annotateIssue(ctx, issue);
+          return toolResult(issue, text);
+        }
+      );
+    }
+  });
+}
+
+// src/plugin.ts
+function linearPlugin() {
+  return defineJuniorPlugin({
+    packageName: "@sentry/junior-linear",
+    manifest: {
+      configKeys: ["team", "project"],
+      description: "Linear issue tracking via hosted MCP server",
+      displayName: "Linear",
+      mcp: {
+        transport: "http",
+        url: "https://mcp.linear.app/mcp",
+        wrappedTools: ["create_issue"]
+      },
+      name: "linear"
+    },
+    hooks: {
+      tools(ctx) {
+        return {
+          createIssue: createLinearIssueTool(ctx)
+        };
+      }
+    }
+  });
+}
+export {
+  linearPlugin
+};

package/dist/plugin.d.ts

@@ -0,0 +1,3 @@
+import { type PluginRegistration } from "@sentry/junior-plugin-api";
+/** Register Linear's hosted MCP provider and Junior-owned wrapper tools. */
+export declare function linearPlugin(): PluginRegistration;

package/dist/tools/create-issue.d.ts

@@ -0,0 +1,40 @@
+import { type ToolRegistrationHookContext } from "@sentry/junior-plugin-api";
+/** Create a Linear issue through the hosted MCP provider and link it to the conversation. */
+export declare function createLinearIssueTool(ctx: ToolRegistrationHookContext): import("@sentry/junior-plugin-api").PluginToolDefinition<{
+    team: string;
+    title: string;
+    description?: string | undefined;
+    priority?: "low" | "medium" | "high" | "urgent" | undefined;
+    project?: string | undefined;
+}, {
+    [x: string]: unknown;
+    ok: true;
+    status: "success";
+    target: "createIssue";
+    data: {
+        issue: {
+            id?: string | undefined;
+            identifier?: string | undefined;
+            title?: string | undefined;
+            url?: string | undefined;
+        } | null;
+        providerText: string;
+    };
+    issue: {
+        id?: string | undefined;
+        identifier?: string | undefined;
+        title?: string | undefined;
+        url?: string | undefined;
+    } | null;
+    providerText: string;
+    truncated?: boolean | undefined;
+    continuation?: {
+        arguments: Record<string, unknown>;
+        reason?: string | undefined;
+    } | undefined;
+    error?: string | {
+        kind: string;
+        message: string;
+        retryable?: boolean | undefined;
+    } | undefined;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-linear",
-  "version": "0.119.0",
+  "version": "0.120.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -11,8 +11,29 @@
     "url": "git+https://github.com/getsentry/junior.git",
     "directory": "packages/junior-linear"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "files": [
-    "plugin.yaml",
+    "dist",
     "skills"
-  ]
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@sentry/junior-plugin-api": "0.120.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "oxlint": "^1.66.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "lint": "oxlint --config ../junior/.oxlintrc.json --deny-warnings src tsup.config.ts",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/skills/linear/SKILL.md

@@ -63,10 +63,11 @@ Attribute the reporter by name when clear from the thread (e.g. "Raised by Alice
 - No session framing remains (channel refs, slash commands, @mentions, Slack thread IDs).
 - Body structure matches complexity — no empty sections, no restated title, no raw research dump.
 
-If any gate fails, revise and re-check before calling the MCP create/update tool.
+If any gate fails, revise and re-check before calling the Linear create/update tool.
 
 6. Execute:
 
+- Create new issues with `linear_createIssue`.
 - For updates, prefer partial changes over full rewrites. Fetch current issue state first if the mutation could overwrite structured fields or duplicate an existing comment.
 - Check for duplicates silently before creating a new issue when the request appears related to existing work.
 

package/plugin.yaml

@@ -1,10 +0,0 @@
-name: linear
-display-name: Linear
-description: Linear issue tracking via hosted MCP server
-
-config-keys:
-  - team
-  - project
-
-mcp:
-  url: https://mcp.linear.app/mcp