npm - @calltelemetry/openclaw-linear - Versions diffs - 0.2.0 - Mend

@calltelemetry/openclaw-linear 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/src/oauth-callback.ts ADDED Viewed

@@ -0,0 +1,113 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const LINEAR_OAUTH_TOKEN_URL = "https://api.linear.app/oauth/token";
+const AUTH_PROFILES_PATH = join(
+  process.env.HOME ?? "/home/claw",
+  ".openclaw",
+  "auth-profiles.json",
+);
+export async function handleOAuthCallback(
+  api: OpenClawPluginApi,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+  const code = url.searchParams.get("code");
+  const error = url.searchParams.get("error");
+  if (error) {
+    res.statusCode = 400;
+    res.end(`OAuth error: ${error} — ${url.searchParams.get("error_description") ?? ""}`);
+    return;
+  }
+  if (!code) {
+    res.statusCode = 400;
+    res.end("Missing authorization code");
+    return;
+  }
+  const clientId = process.env.LINEAR_CLIENT_ID;
+  const clientSecret = process.env.LINEAR_CLIENT_SECRET;
+  const redirectUri = process.env.LINEAR_REDIRECT_URI ?? `${req.headers["x-forwarded-proto"] ?? "https"}://${req.headers.host}/linear/oauth/callback`;
+  if (!clientId || !clientSecret) {
+    res.statusCode = 500;
+    res.end("LINEAR_CLIENT_ID and LINEAR_CLIENT_SECRET must be set");
+    return;
+  }
+  api.logger.info("Linear OAuth: exchanging authorization code for token...");
+  try {
+    const tokenRes = await fetch(LINEAR_OAUTH_TOKEN_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        client_id: clientId,
+        client_secret: clientSecret,
+        redirect_uri: redirectUri,
+      }),
+    });
+    if (!tokenRes.ok) {
+      const errText = await tokenRes.text();
+      api.logger.error(`Linear OAuth token exchange failed: ${errText}`);
+      res.statusCode = 502;
+      res.end(`Token exchange failed: ${errText}`);
+      return;
+    }
+    const tokens = await tokenRes.json();
+    api.logger.info(`Linear OAuth: token received (expires_in: ${tokens.expires_in}s, scopes: ${tokens.scope})`);
+    // Store in auth profile store
+    let store: any = { version: 1, profiles: {} };
+    try {
+      const raw = readFileSync(AUTH_PROFILES_PATH, "utf8");
+      store = JSON.parse(raw);
+    } catch {
+      // Fresh store
+    }
+    store.profiles = store.profiles ?? {};
+    store.profiles["linear:default"] = {
+      type: "oauth",
+      provider: "linear",
+      accessToken: tokens.access_token,
+      access: tokens.access_token,
+      refreshToken: tokens.refresh_token ?? null,
+      refresh: tokens.refresh_token ?? null,
+      expiresAt: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : null,
+      expires: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : null,
+      scope: tokens.scope,
+    };
+    writeFileSync(AUTH_PROFILES_PATH, JSON.stringify(store, null, 2), "utf8");
+    api.logger.info("Linear OAuth: token stored in auth profile store");
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/html");
+    res.end(`
+      <html><body style="font-family: system-ui; max-width: 600px; margin: 80px auto; text-align: center;">
+        <h1>Linear OAuth Complete</h1>
+        <p>Access token stored. Scopes: <code>${tokens.scope ?? "unknown"}</code></p>
+        <p>The Linear agent pipeline is now active. You can close this tab.</p>
+        <p style="color: #888; font-size: 0.9em;">Restart the gateway to pick up the new token.</p>
+      </body></html>
+    `);
+  } catch (err) {
+    api.logger.error(`Linear OAuth error: ${err}`);
+    res.statusCode = 500;
+    res.end(`OAuth error: ${String(err)}`);
+  }
+}

package/src/pipeline.ts ADDED Viewed

@@ -0,0 +1,212 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { LinearAgentApi, ActivityContent } from "./linear-api.js";
+import { runAgent } from "./agent.js";
+export interface PipelineContext {
+  api: OpenClawPluginApi;
+  linearApi: LinearAgentApi;
+  agentSessionId: string;
+  agentId: string;
+  issue: {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string | null;
+  };
+  promptContext?: unknown;
+}
+function emit(ctx: PipelineContext, content: ActivityContent): Promise<void> {
+  return ctx.linearApi.emitActivity(ctx.agentSessionId, content).catch((err) => {
+    ctx.api.logger.error(`Failed to emit activity: ${err}`);
+  });
+}
+// ── Stage 1: Planner ───────────────────────────────────────────────
+export async function runPlannerStage(ctx: PipelineContext): Promise<string | null> {
+  await emit(ctx, { type: "thought", body: `Analyzing issue ${ctx.issue.identifier}...` });
+  const issueDetails = await ctx.linearApi.getIssueDetails(ctx.issue.id).catch(() => null);
+  const description = issueDetails?.description ?? ctx.issue.description ?? "(no description)";
+  const comments = issueDetails?.comments?.nodes ?? [];
+  const commentSummary = comments
+    .slice(-5)
+    .map((c) => `${c.user?.name ?? "Unknown"}: ${c.body}`)
+    .join("\n");
+  const message = `You are a planner agent. Analyze this Linear issue and create an implementation plan.
+## Issue: ${ctx.issue.identifier} — ${ctx.issue.title}
+**Description:**
+${description}
+${commentSummary ? `**Recent comments:**\n${commentSummary}` : ""}
+${ctx.promptContext ? `**Additional context:**\n${JSON.stringify(ctx.promptContext)}` : ""}
+## Instructions
+1. Analyze the issue thoroughly
+2. Break it into concrete implementation steps
+3. Identify files that need to change
+4. Note any risks or dependencies
+5. Output your plan in markdown format
+Output ONLY the plan, nothing else.`;
+  await emit(ctx, { type: "action", action: "Planning", parameter: ctx.issue.identifier });
+  const result = await runAgent({
+    api: ctx.api,
+    agentId: ctx.agentId,
+    sessionId: `linear-plan-${ctx.agentSessionId}`,
+    message,
+    timeoutMs: 5 * 60_000,
+  });
+  if (!result.success) {
+    await emit(ctx, { type: "error", body: `Planning failed: ${result.output.slice(0, 500)}` });
+    return null;
+  }
+  const plan = result.output;
+  // Post plan as a Linear comment
+  await ctx.linearApi.createComment(
+    ctx.issue.id,
+    `## Implementation Plan\n\n${plan}\n\n---\n*Reply to this comment to approve the plan and begin implementation.*`,
+  );
+  await emit(ctx, {
+    type: "elicitation",
+    body: "I've posted an implementation plan as a comment. Please review and reply to approve.",
+  });
+  return plan;
+}
+// ── Stage 2: Implementor ──────────────────────────────────────────
+export async function runImplementorStage(
+  ctx: PipelineContext,
+  plan: string,
+): Promise<string | null> {
+  await emit(ctx, { type: "thought", body: "Plan approved. Starting implementation..." });
+  const message = `You are an implementor agent. Execute this plan for issue ${ctx.issue.identifier}.
+## Issue: ${ctx.issue.identifier} — ${ctx.issue.title}
+## Approved Plan:
+${plan}
+## Instructions
+1. Follow the plan step by step
+2. Write the code changes
+3. Create commits for each logical change
+4. If the plan involves creating a PR, do so
+5. Report what you did and any files changed
+Be thorough but stay within scope of the plan.`;
+  await emit(ctx, { type: "action", action: "Implementing", parameter: ctx.issue.identifier });
+  const result = await runAgent({
+    api: ctx.api,
+    agentId: ctx.agentId,
+    sessionId: `linear-impl-${ctx.agentSessionId}`,
+    message,
+    timeoutMs: 10 * 60_000,
+  });
+  if (!result.success) {
+    await emit(ctx, { type: "error", body: `Implementation failed: ${result.output.slice(0, 500)}` });
+    return null;
+  }
+  await emit(ctx, { type: "action", action: "Implementation complete", result: "Proceeding to audit" });
+  return result.output;
+}
+// ── Stage 3: Auditor ──────────────────────────────────────────────
+export async function runAuditorStage(
+  ctx: PipelineContext,
+  plan: string,
+  implResult: string,
+): Promise<void> {
+  await emit(ctx, { type: "thought", body: "Auditing implementation against the plan..." });
+  const message = `You are an auditor. Review this implementation against the original plan.
+## Issue: ${ctx.issue.identifier} — ${ctx.issue.title}
+## Original Plan:
+${plan}
+## Implementation Result:
+${implResult}
+## Instructions
+1. Verify each plan step was completed
+2. Check for any missed items
+3. Note any concerns or improvements needed
+4. Provide a pass/fail verdict with reasoning
+5. Output a concise audit summary in markdown
+Output ONLY the audit summary.`;
+  await emit(ctx, { type: "action", action: "Auditing", parameter: ctx.issue.identifier });
+  const result = await runAgent({
+    api: ctx.api,
+    agentId: ctx.agentId,
+    sessionId: `linear-audit-${ctx.agentSessionId}`,
+    message,
+    timeoutMs: 5 * 60_000,
+  });
+  const auditSummary = result.success ? result.output : `Audit failed: ${result.output.slice(0, 500)}`;
+  await ctx.linearApi.createComment(
+    ctx.issue.id,
+    `## Audit Report\n\n${auditSummary}`,
+  );
+  await emit(ctx, {
+    type: "response",
+    body: `Completed work on ${ctx.issue.identifier}. Plan, implementation, and audit posted as comments.`,
+  });
+}
+// ── Full Pipeline ─────────────────────────────────────────────────
+export async function runFullPipeline(ctx: PipelineContext): Promise<void> {
+  try {
+    // Stage 1: Plan
+    const plan = await runPlannerStage(ctx);
+    if (!plan) return;
+    // Pipeline pauses here — user must reply to approve.
+    // The "prompted" webhook will call resumePipeline().
+  } catch (err) {
+    ctx.api.logger.error(`Pipeline error: ${err}`);
+    await emit(ctx, { type: "error", body: `Pipeline failed: ${String(err).slice(0, 500)}` });
+  }
+}
+export async function resumePipeline(ctx: PipelineContext, plan: string): Promise<void> {
+  try {
+    // Stage 2: Implement
+    const implResult = await runImplementorStage(ctx, plan);
+    if (!implResult) return;
+    // Stage 3: Audit
+    await runAuditorStage(ctx, plan, implResult);
+  } catch (err) {
+    ctx.api.logger.error(`Pipeline error: ${err}`);
+    await emit(ctx, { type: "error", body: `Pipeline failed: ${String(err).slice(0, 500)}` });
+  }
+}

package/src/tools.ts ADDED Viewed

@@ -0,0 +1,84 @@
+import type { AnyAgentTool, OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { LinearClient } from "./client.js";
+export function createLinearTools(api: OpenClawPluginApi, ctx: OpenClawPluginToolContext): AnyAgentTool[] {
+  const getClient = () => {
+    // In a real implementation, we would resolve the token from auth profiles
+    // For now, we'll try to get it from environment or a known profile
+    const token = process.env.LINEAR_ACCESS_TOKEN;
+    if (!token) {
+      throw new Error("Linear access token not found. Please authenticate first.");
+    }
+    return new LinearClient(token);
+  };
+  return [
+    {
+      name: "linear_list_issues",
+      description: "List issues from a Linear workspace",
+      parameters: {
+        type: "object",
+        properties: {
+          limit: { type: "number", description: "Max issues to return", default: 10 },
+          teamId: { type: "string", description: "Filter by team ID" }
+        }
+      },
+      execute: async ({ limit, teamId }) => {
+        const client = getClient();
+        const data = await client.listIssues({ limit, teamId });
+        return jsonResult({
+          message: `Found ${data.issues.nodes.length} issues`,
+          issues: data.issues.nodes
+        });
+      }
+    },
+    {
+      name: "linear_create_issue",
+      description: "Create a new issue in Linear",
+      parameters: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "Issue title" },
+          description: { type: "string", description: "Issue description" },
+          teamId: { type: "string", description: "Team ID" }
+        },
+        required: ["title", "teamId"]
+      },
+      execute: async ({ title, description, teamId }) => {
+        const client = getClient();
+        const data = await client.createIssue({ title, description, teamId });
+        if (data.issueCreate.success) {
+          return jsonResult({
+            message: "Created issue successfully",
+            issue: data.issueCreate.issue
+          });
+        }
+        return jsonResult({ message: "Failed to create issue" });
+      }
+    },
+    {
+      name: "linear_add_comment",
+      description: "Add a comment to a Linear issue",
+      parameters: {
+        type: "object",
+        properties: {
+          issueId: { type: "string", description: "Issue ID" },
+          body: { type: "string", description: "Comment body" }
+        },
+        required: ["issueId", "body"]
+      },
+      execute: async ({ issueId, body }) => {
+        const client = getClient();
+        const data = await client.addComment({ issueId, body });
+        if (data.commentCreate.success) {
+          return jsonResult({
+            message: "Added comment successfully",
+            commentId: data.commentCreate.comment.id
+          });
+        }
+        return jsonResult({ message: "Failed to add comment" });
+      }
+    }
+  ];
+}

package/src/webhook.test.ts ADDED Viewed

@@ -0,0 +1,191 @@
+import type { AddressInfo } from "node:net";
+import { createServer } from "node:http";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+// Mock the pipeline module
+const { runPlannerStageMock, runFullPipelineMock, resumePipelineMock } = vi.hoisted(() => ({
+  runPlannerStageMock: vi.fn().mockResolvedValue("mock plan"),
+  runFullPipelineMock: vi.fn().mockResolvedValue(undefined),
+  resumePipelineMock: vi.fn().mockResolvedValue(undefined),
+}));
+vi.mock("./pipeline.js", () => ({
+  runPlannerStage: runPlannerStageMock,
+  runFullPipeline: runFullPipelineMock,
+  resumePipeline: resumePipelineMock,
+}));
+// Mock the linear-api module
+vi.mock("./linear-api.js", () => ({
+  LinearAgentApi: class MockLinearAgentApi {
+    emitActivity = vi.fn().mockResolvedValue(undefined);
+    createComment = vi.fn().mockResolvedValue("comment-id");
+    getIssueDetails = vi.fn().mockResolvedValue(null);
+    updateSession = vi.fn().mockResolvedValue(undefined);
+  },
+  resolveLinearToken: vi.fn().mockReturnValue({
+    accessToken: "test-token",
+    source: "env",
+  }),
+}));
+import { handleLinearWebhook } from "./webhook.js";
+function createApi(): OpenClawPluginApi {
+  return {
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+    runtime: {},
+    pluginConfig: {},
+  } as unknown as OpenClawPluginApi;
+}
+async function withServer(
+  handler: Parameters<typeof createServer>[0],
+  fn: (baseUrl: string) => Promise<void>,
+) {
+  const server = createServer(handler);
+  await new Promise<void>((resolve) => {
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const address = server.address() as AddressInfo | null;
+  if (!address) {
+    throw new Error("missing server address");
+  }
+  try {
+    await fn(`http://127.0.0.1:${address.port}`);
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+async function postWebhook(payload: unknown, path = "/linear/webhook") {
+  const api = createApi();
+  let status = 0;
+  let body = "";
+  await withServer(
+    async (req, res) => {
+      const handled = await handleLinearWebhook(api, req, res);
+      if (!handled) {
+        res.statusCode = 404;
+        res.end("not found");
+      }
+    },
+    async (baseUrl) => {
+      const response = await fetch(`${baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+      });
+      status = response.status;
+      body = await response.text();
+    },
+  );
+  return { api, status, body };
+}
+afterEach(() => {
+  runPlannerStageMock.mockReset().mockResolvedValue("mock plan");
+  runFullPipelineMock.mockReset().mockResolvedValue(undefined);
+  resumePipelineMock.mockReset().mockResolvedValue(undefined);
+});
+describe("handleLinearWebhook", () => {
+  it("responds 200 to AgentSession create within time limit", async () => {
+    const payload = {
+      type: "AgentSession",
+      action: "create",
+      data: {
+        id: "sess-1",
+        context: { commentBody: "Please investigate this issue" },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "ENG-123",
+        title: "Fix webhook routing",
+      },
+    };
+    const result = await postWebhook(payload);
+    expect(result.status).toBe(200);
+    expect(result.body).toBe("ok");
+  });
+  it("logs error when session or issue data is missing", async () => {
+    const payload = {
+      type: "AgentSession",
+      action: "create",
+      data: { id: null },
+      issue: null,
+    };
+    const result = await postWebhook(payload);
+    expect(result.status).toBe(200);
+    expect((result.api.logger.error as any).mock.calls.length).toBeGreaterThan(0);
+  });
+  it("responds 200 to AgentSession prompted", async () => {
+    const payload = {
+      type: "AgentSession",
+      action: "prompted",
+      data: {
+        id: "sess-prompted",
+        context: { prompt: "Looks good, approved!" },
+      },
+      issue: {
+        id: "issue-2",
+        identifier: "ENG-124",
+        title: "Approved issue",
+      },
+    };
+    const result = await postWebhook(payload);
+    expect(result.status).toBe(200);
+    expect(result.body).toBe("ok");
+  });
+  it("responds 200 to unknown webhook types", async () => {
+    const payload = {
+      type: "Issue",
+      action: "update",
+      data: { id: "issue-5" },
+    };
+    const result = await postWebhook(payload);
+    expect(result.status).toBe(200);
+    expect(result.body).toBe("ok");
+  });
+  it("returns 405 for non-POST methods", async () => {
+    const api = createApi();
+    let status = 0;
+    await withServer(
+      async (req, res) => {
+        await handleLinearWebhook(api, req, res);
+      },
+      async (baseUrl) => {
+        const response = await fetch(`${baseUrl}/linear/webhook`, {
+          method: "GET",
+        });
+        status = response.status;
+      },
+    );
+    expect(status).toBe(405);
+  });
+});