@yannelli/paseo-linear-plugin 0.0.0-stage → 0.3.0

package/index.client.tsx

@@ -0,0 +1,111 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { LinearPanel, LinearScreen } from "./client/browser";
+import { openPluginScreen, registerScreen } from "./client/compat";
+import { ConnectionSettings } from "./client/settings-connection";
+import { ProjectSettings } from "./client/settings-projects";
+import { PromptSettings } from "./client/settings-prompts";
+import { focusIssue, panelScope, SCREEN_SCOPE, updateBrowser } from "./client/store";
+import { IssueCardRow } from "./client/timeline-card";
+import { issueAttachments } from "./shared/issues";
+import { ISSUE_CARD_KIND, IssueCardSchema, LINEAR_IDENTIFIER } from "./shared/linear";
+
+const SCREEN_ID = "linear";
+const PANEL_ID = "issues";
+
+export default function contribute(client: PluginClientContext) {
+  client.addAttachmentSource(issueAttachments);
+  registerScreen(client, {
+    id: SCREEN_ID,
+    title: "Linear",
+    icon: "SquareKanban",
+    Component: LinearScreen,
+  });
+  client.addWorkspacePanel({
+    id: PANEL_ID,
+    title: "Linear",
+    icon: "SquareKanban",
+    context: "workspace",
+    locations: ["workspace", "explorer"],
+    Component: LinearPanel,
+  });
+  client.addSettingsScreen({
+    id: "connection",
+    title: "Account",
+    icon: "KeyRound",
+    Component: ConnectionSettings,
+  });
+  client.addSettingsScreen({
+    id: "prompts",
+    title: "Prompts",
+    icon: "MessageSquare",
+    Component: PromptSettings,
+  });
+  client.addSettingsScreen({
+    id: "projects",
+    title: "Projects",
+    icon: "FolderGit2",
+    Component: ProjectSettings,
+  });
+  client.addCommandCenterItem({
+    id: "open-issues",
+    title: "Linear: Open issues",
+    icon: "SquareKanban",
+    keywords: ["linear", "issues", "tickets"],
+    context: "global",
+    onSelect(context) {
+      openPluginScreen(context, SCREEN_ID);
+    },
+  });
+  client.addCommandCenterItem({
+    id: "create-issue",
+    title: "Linear: Create issue",
+    icon: "Plus",
+    keywords: ["linear", "new", "ticket"],
+    context: "global",
+    onSelect(context) {
+      updateBrowser(SCREEN_SCOPE, { creating: true });
+      openPluginScreen(context, SCREEN_ID);
+    },
+  });
+  client.addCommandCenterItem({
+    id: "workspace-issues",
+    title: "Linear: Show issues in this workspace",
+    icon: "SquareKanban",
+    keywords: ["linear", "panel"],
+    context: "workspace",
+    onSelect({ openPanel }) {
+      openPanel(PANEL_ID);
+    },
+  });
+  client.addCommandCenterItem({
+    id: "settings",
+    title: "Linear: Settings",
+    icon: "Settings",
+    keywords: ["linear", "api key", "prompts", "projects"],
+    context: "global",
+    onSelect({ openSettings }) {
+      openSettings("connection");
+    },
+  });
+  client.addSlashCommand({
+    name: "linear",
+    description: "Open Linear issues, or jump to one by key",
+    argumentHint: "[ENG-123 or search]",
+    context: "workspace",
+    onSubmit({ args, workspace, openPanel }) {
+      const scope = panelScope(workspace.id);
+      const text = args.trim();
+      if (LINEAR_IDENTIFIER.test(text)) focusIssue(scope, text.toUpperCase());
+      else if (text)
+        updateBrowser(scope, { query: text, issueId: null, assignee: "anyone", status: "all" });
+      openPanel(PANEL_ID);
+    },
+  });
+  client.addTimelineRenderer({
+    kind: ISSUE_CARD_KIND,
+    version: 1,
+    schema: IssueCardSchema,
+    Component: IssueCardRow,
+  });
+  return () => {};
+}

package/index.server.ts

@@ -0,0 +1,12 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { createCredentialStore, defaultCredentialPath } from "./server/credentials";
+import { registerHandlers } from "./server/handlers";
+import { linearSettings } from "./shared/settings";
+
+export default function contribute(server: PluginServerContext) {
+  server.registerSettings(linearSettings);
+  registerHandlers(server, {
+    credentials: createCredentialStore({ file: defaultCredentialPath() }),
+  });
+  return () => {};
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@yannelli/paseo-linear-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Browse and triage Linear issues in Paseo and start agents from them",
+  "license": "Apache-2.0",
+  "type": "module",
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "linear"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yannelli/paseo-linear-plugin.git"
+  },
+  "homepage": "https://github.com/yannelli/paseo-linear-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/yannelli/paseo-linear-plugin/issues"
+  },
+  "files": [
+    "paseo-plugin.json",
+    "OVERVIEW.md",
+    "NOTICE",
+    "index.client.tsx",
+    "index.server.ts",
+    "client/",
+    "server/",
+    "shared/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run && node --test test/*.test.mjs",
+    "check": "npm run typecheck && npm test",
+    "release:dry-run": "node scripts/release.mjs --dry-run"
+  },
+  "devDependencies": {
+    "@getpaseo/plugin": "0.10.3",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/node": "^24.19.1",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6",
+    "zod": "^4.4.3"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "linear",
+  "description": "Browse, triage, and create Linear issues, and start agents that implement or review them",
+  "requirements": {
+    "paseo": ">=0.10.0"
+  }
+}

package/server/cache.ts

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+
+export interface CachedValue<T> {
+  value: T;
+  fetchedAt: number;
+}
+
+export interface ResponseCache {
+  get<T>(key: string): CachedValue<T> | null;
+  set(key: string, value: unknown): void;
+  /** Drops every entry whose key starts with `prefix`. */
+  drop(prefix: string): void;
+  clear(): void;
+  size(): number;
+}
+
+// Entries are partitioned by a hash of the API key, so two Linear workspaces never share data.
+export function keyFingerprint(apiKey: string): string {
+  return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+}
+
+export function cacheKey(fingerprint: string, kind: string, params: unknown = null): string {
+  return `${fingerprint}:${kind}:${JSON.stringify(params)}`;
+}
+
+export function createResponseCache(options: {
+  maxEntries: number;
+  maxAgeMs: number;
+  now?: () => number;
+}): ResponseCache {
+  const now = options.now ?? Date.now;
+  const entries = new Map<string, CachedValue<unknown>>();
+
+  return {
+    get<T>(key: string) {
+      const entry = entries.get(key);
+      if (!entry) return null;
+      if (now() - entry.fetchedAt > options.maxAgeMs) {
+        entries.delete(key);
+        return null;
+      }
+      // Map order is insertion order; re-inserting marks the entry as recently used.
+      entries.delete(key);
+      entries.set(key, entry);
+      return entry as CachedValue<T>;
+    },
+    set(key, value) {
+      entries.delete(key);
+      entries.set(key, { value, fetchedAt: now() });
+      while (entries.size > options.maxEntries) {
+        const oldest = entries.keys().next().value;
+        if (oldest === undefined) break;
+        entries.delete(oldest);
+      }
+    },
+    drop(prefix) {
+      for (const key of [...entries.keys()]) {
+        if (key.startsWith(prefix)) entries.delete(key);
+      }
+    },
+    clear() {
+      entries.clear();
+    },
+    size() {
+      return entries.size;
+    },
+  };
+}

package/server/credentials.ts

@@ -0,0 +1,101 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import type { KeySource } from "../shared/linear";
+
+// Version 1 files hold only `apiKey`. Version 2 adds keys for individual Paseo projects.
+const CredentialFileSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  projects: z.record(z.string(), z.object({ apiKey: z.string().min(1) })).default({}),
+});
+type CredentialFile = z.infer<typeof CredentialFileSchema>;
+
+export interface ResolvedCredential {
+  apiKey: string;
+  source: KeySource;
+}
+
+export interface CredentialStore {
+  /** Project key, then the saved default key, then LINEAR_API_KEY. */
+  resolve(projectId?: string | null): Promise<ResolvedCredential | null>;
+  save(apiKey: string, projectId?: string | null): Promise<void>;
+  clear(projectId?: string | null): Promise<void>;
+  projectKeys(): Promise<{ projectId: string; apiKey: string }[]>;
+}
+
+export function defaultCredentialPath(env: NodeJS.ProcessEnv = process.env): string {
+  const home = env.PASEO_HOME?.trim() || path.join(homedir(), ".paseo");
+  return path.join(home, "plugin-data", "linear", "credentials.json");
+}
+
+export function createCredentialStore(options: {
+  file: string;
+  env?: NodeJS.ProcessEnv;
+}): CredentialStore {
+  const env = options.env ?? process.env;
+
+  async function read(): Promise<CredentialFile> {
+    try {
+      const parsed = CredentialFileSchema.safeParse(
+        JSON.parse(await readFile(options.file, "utf8")),
+      );
+      return parsed.success ? parsed.data : { projects: {} };
+    } catch {
+      return { projects: {} };
+    }
+  }
+
+  async function write(next: CredentialFile): Promise<void> {
+    if (!next.apiKey && Object.keys(next.projects).length === 0) {
+      await rm(options.file, { force: true });
+      return;
+    }
+    await mkdir(path.dirname(options.file), { recursive: true, mode: 0o700 });
+    const temporary = `${options.file}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(next), { mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, options.file);
+  }
+
+  return {
+    async resolve(projectId) {
+      const stored = await read();
+      const projectKey = projectId ? stored.projects[projectId]?.apiKey : undefined;
+      if (projectKey) return { apiKey: projectKey, source: "project" };
+      if (stored.apiKey) return { apiKey: stored.apiKey, source: "file" };
+      const fromEnv = env.LINEAR_API_KEY?.trim();
+      return fromEnv ? { apiKey: fromEnv, source: "environment" } : null;
+    },
+    async save(apiKey, projectId) {
+      const stored = await read();
+      const key = apiKey.trim();
+      if (projectId) {
+        await write({ ...stored, projects: { ...stored.projects, [projectId]: { apiKey: key } } });
+      } else {
+        await write({ ...stored, apiKey: key });
+      }
+    },
+    async clear(projectId) {
+      const stored = await read();
+      if (projectId) {
+        const projects = { ...stored.projects };
+        delete projects[projectId];
+        await write({ ...stored, projects });
+      } else {
+        await write({ projects: stored.projects });
+      }
+    },
+    async projectKeys() {
+      const stored = await read();
+      return Object.entries(stored.projects).map(([projectId, entry]) => ({
+        projectId,
+        apiKey: entry.apiKey,
+      }));
+    },
+  };
+}
+
+export function keyHint(apiKey: string): string {
+  return apiKey.length > 8 ? `…${apiKey.slice(-4)}` : "…";
+}

package/server/graphql.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+
+export const LINEAR_ENDPOINT = "https://api.linear.app/graphql";
+
+export class LinearApiError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LinearApiError";
+  }
+}
+
+export interface LinearGraphqlOptions {
+  apiKey: string;
+  endpoint?: string;
+  request?: typeof fetch;
+}
+
+export type LinearGraphql = (
+  query: string,
+  variables?: Record<string, unknown>,
+) => Promise<unknown>;
+
+const GraphqlEnvelopeSchema = z.object({
+  data: z.unknown().optional(),
+  errors: z.array(z.object({ message: z.string() }).passthrough()).optional(),
+});
+
+function describeHttpFailure(status: number): string {
+  if (status === 401 || status === 403) return "Linear rejected the API key";
+  if (status === 429) return "Linear rate limit reached. Try again shortly";
+  return `Linear API request failed with HTTP ${status}`;
+}
+
+export function createLinearGraphql(options: LinearGraphqlOptions): LinearGraphql {
+  const apiKey = options.apiKey.trim();
+  if (!apiKey) throw new LinearApiError("Connect Linear: add an API key in Linear settings");
+  const endpoint = options.endpoint ?? LINEAR_ENDPOINT;
+  const request = options.request ?? fetch;
+
+  return async (query, variables = {}) => {
+    const response = await request(endpoint, {
+      method: "POST",
+      headers: { Authorization: apiKey, "Content-Type": "application/json" },
+      body: JSON.stringify({ query, variables }),
+    });
+    // Linear reports auth and validation failures as HTTP 400 with GraphQL errors.
+    const text = await response.text();
+    let body: z.infer<typeof GraphqlEnvelopeSchema> | null = null;
+    try {
+      body = GraphqlEnvelopeSchema.parse(JSON.parse(text));
+    } catch {
+      body = null;
+    }
+    if (body?.errors && body.errors.length > 0) {
+      const message = body.errors.map((error) => error.message).join("; ");
+      throw new LinearApiError(
+        response.status === 401 || response.status === 403
+          ? describeHttpFailure(response.status)
+          : message,
+      );
+    }
+    if (!response.ok) throw new LinearApiError(describeHttpFailure(response.status));
+    if (!body || body.data === undefined || body.data === null) {
+      throw new LinearApiError("Linear returned no data");
+    }
+    return body.data;
+  };
+}

package/server/handlers.ts

@@ -0,0 +1,172 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import {
+  attachIssueCardRpc,
+  authClearRpc,
+  authSaveRpc,
+  authStatusRpc,
+  cachedCatalogRpc,
+  cachedIssueRpc,
+  cachedIssuesRpc,
+  catalogRpc,
+  createCommentRpc,
+  createIssueRpc,
+  getIssueRpc,
+  ISSUE_CARD_KIND,
+  type IssueQuery,
+  listIssuesRpc,
+  updateIssueRpc,
+} from "../shared/linear";
+import { searchIssuesRpc } from "../shared/issues";
+import { cacheKey, createResponseCache, keyFingerprint, type ResponseCache } from "./cache";
+import { type CredentialStore, keyHint } from "./credentials";
+import { createLinearGraphql, LinearApiError } from "./graphql";
+import { createLinearIssueSearch } from "./linear";
+import { createLinearService, type LinearService } from "./queries";
+
+export interface HandlerDependencies {
+  credentials: CredentialStore;
+  endpoint?: string;
+  cache?: ResponseCache;
+}
+
+type ProjectId = string | null | undefined;
+
+// The cache key ignores the key scope and cursor fields that do not change the response.
+function listKey(query: IssueQuery) {
+  const { teamId, assignee, status, query: text, sort = "updated", after } = query;
+  return { teamId, assignee, status, query: text.trim(), sort, after };
+}
+
+export function registerHandlers(server: PluginServerContext, dependencies: HandlerDependencies) {
+  const { credentials, endpoint } = dependencies;
+  const cache =
+    dependencies.cache ?? createResponseCache({ maxEntries: 300, maxAgeMs: 24 * 60 * 60 * 1000 });
+
+  async function apiKey(projectId?: ProjectId): Promise<string> {
+    const credential = await credentials.resolve(projectId);
+    if (!credential) throw new LinearApiError("Connect Linear: add an API key in Linear settings");
+    return credential.apiKey;
+  }
+
+  async function connect(projectId: ProjectId) {
+    const key = await apiKey(projectId);
+    return {
+      linear: createLinearService(createLinearGraphql({ apiKey: key, endpoint })),
+      fingerprint: keyFingerprint(key),
+    };
+  }
+
+  /** Returns the cached response for a key scope without calling Linear. */
+  async function readCache<T>(projectId: ProjectId, kind: string, params: unknown) {
+    const credential = await credentials.resolve(projectId);
+    const entry = credential
+      ? cache.get<T>(cacheKey(keyFingerprint(credential.apiKey), kind, params))
+      : null;
+    return entry
+      ? { value: entry.value, fetchedAt: new Date(entry.fetchedAt).toISOString() }
+      : { value: null, fetchedAt: null };
+  }
+
+  async function fetchAndStore<T>(
+    projectId: ProjectId,
+    kind: string,
+    params: unknown,
+    load: (linear: LinearService) => Promise<T>,
+  ): Promise<T> {
+    const { linear, fingerprint } = await connect(projectId);
+    const value = await load(linear);
+    cache.set(cacheKey(fingerprint, kind, params), value);
+    return value;
+  }
+
+  // Edits change list order and issue details, so every list and issue entry for the key goes.
+  async function mutate<T>(projectId: ProjectId, run: (linear: LinearService) => Promise<T>) {
+    const { linear, fingerprint } = await connect(projectId);
+    try {
+      return await run(linear);
+    } finally {
+      cache.drop(`${fingerprint}:issues:`);
+      cache.drop(`${fingerprint}:issue:`);
+    }
+  }
+
+  server.handle(authStatusRpc, async ({ projectId }) => {
+    const credential = await credentials.resolve(projectId);
+    const projectKeys = await credentials.projectKeys();
+    return {
+      configured: credential !== null,
+      source: credential?.source ?? null,
+      keyHint: credential ? keyHint(credential.apiKey) : null,
+      projectKeys: projectKeys.map((entry) => ({
+        projectId: entry.projectId,
+        keyHint: keyHint(entry.apiKey),
+      })),
+    };
+  });
+
+  server.handle(authSaveRpc, async ({ apiKey: candidate, projectId }) => {
+    // Validate the key against Linear before persisting it.
+    const linear = createLinearService(createLinearGraphql({ apiKey: candidate, endpoint }));
+    const catalog = await linear.catalog();
+    await credentials.save(candidate, projectId);
+    cache.clear();
+    return { viewerName: catalog.viewer.displayName, organizationName: catalog.organization.name };
+  });
+
+  server.handle(authClearRpc, async ({ projectId }) => {
+    await credentials.clear(projectId);
+    cache.clear();
+    return { configured: (await credentials.resolve(projectId)) !== null };
+  });
+
+  server.handle(catalogRpc, async ({ projectId }) =>
+    fetchAndStore(projectId, "catalog", null, (linear) => linear.catalog()),
+  );
+  server.handle(listIssuesRpc, async ({ projectId, ...query }) =>
+    fetchAndStore(projectId, "issues", listKey(query), (linear) => linear.listIssues(query)),
+  );
+  server.handle(getIssueRpc, async ({ id, projectId }) =>
+    fetchAndStore(projectId, "issue", id, async (linear) => ({ issue: await linear.getIssue(id) })),
+  );
+
+  server.handle(cachedCatalogRpc, async ({ projectId }) => readCache(projectId, "catalog", null));
+  server.handle(cachedIssuesRpc, async ({ projectId, ...query }) =>
+    readCache(projectId, "issues", listKey(query)),
+  );
+  server.handle(cachedIssueRpc, async ({ id, projectId }) => readCache(projectId, "issue", id));
+
+  server.handle(updateIssueRpc, async ({ id, patch, projectId }) => ({
+    issue: await mutate(projectId, (linear) => linear.updateIssue(id, patch)),
+  }));
+  server.handle(createIssueRpc, async ({ projectId, linearProjectId, ...input }) => ({
+    issue: await mutate(projectId, (linear) =>
+      linear.createIssue(
+        linearProjectId === undefined ? input : { ...input, projectId: linearProjectId },
+      ),
+    ),
+  }));
+  server.handle(createCommentRpc, async ({ issueId, body, projectId }) => ({
+    comment: await mutate(projectId, (linear) => linear.createComment(issueId, body)),
+  }));
+
+  server.handle(searchIssuesRpc, async ({ query }) =>
+    createLinearIssueSearch({ apiKey: await apiKey(), endpoint }).search(query),
+  );
+
+  // Only the plugin's daemon session may append timeline rows, so the client asks the server.
+  server.handle(attachIssueCardRpc, async ({ agentId, card }, { paseo }) => {
+    try {
+      await paseo.agents.ref(agentId).timeline.append({
+        type: "plugin",
+        id: `linear-issue-${card.identifier}`,
+        kind: ISSUE_CARD_KIND,
+        version: 1,
+        data: card,
+      });
+      return { attached: true };
+    } catch (error) {
+      console.error("Linear issue card was not attached", error);
+      return { attached: false };
+    }
+  });
+}