@subsimplicity/pi-extension-linear 0.0.1

package/src/tools.ts

@@ -0,0 +1,202 @@
+import {
+  CommentIssueParams,
+  CreateIssueParams,
+  EmptyParams,
+  GetIssueParams,
+  ListStatesParams,
+  MyWorkParams,
+  SearchIssuesParams,
+  UpdateIssueParams,
+} from "./schemas.ts";
+import {
+  formatIssue,
+  formatIssueSearch,
+  formatMyWork,
+  formatStates,
+  formatTeams,
+  formatViewer,
+} from "./format.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { LinearClient } from "./client.ts";
+import { textResult } from "./results.ts";
+
+export function registerLinearTools(pi: ExtensionAPI): void {
+  const client = new LinearClient();
+
+  pi.registerTool({
+    description:
+      "Check Linear API credentials and return the authenticated Linear user. Uses LINEAR_API_KEY or LINEAR_ACCESS_TOKEN.",
+    async execute(_toolCallId, _params, signal) {
+      const viewer = await client.viewer(signal);
+      return textResult(`Linear connected as ${formatViewer(viewer)}`, {
+        viewer,
+      });
+    },
+    label: "Linear Setup",
+    name: "linear_setup",
+    parameters: EmptyParams,
+    promptGuidelines: [
+      "Use linear_setup when diagnosing Linear authentication or before using Linear tools if credentials may be missing.",
+    ],
+    promptSnippet:
+      "Check Linear API credentials and identify the authenticated user",
+  });
+
+  pi.registerTool({
+    description:
+      "Fetch a Linear issue by UUID or identifier, including description, metadata, labels, project, assignee, delegate, and recent comments.",
+    async execute(_toolCallId, params: GetIssueParams, signal) {
+      const issue = await client.issue(
+        params.issueId,
+        params.commentsLimit,
+        signal,
+      );
+      return textResult(formatIssue(issue), { issue });
+    },
+    label: "Linear Get Issue",
+    name: "linear_get_issue",
+    parameters: GetIssueParams,
+    promptGuidelines: [
+      "Use linear_get_issue when the user references a Linear issue key such as ENG-123 or asks for issue details.",
+      "Use Linear issue descriptions and comments as planning context, but verify repository state with normal file and shell tools before making code changes.",
+    ],
+    promptSnippet: "Fetch a Linear issue with metadata and recent comments",
+  });
+
+  pi.registerTool({
+    description:
+      "Search Linear issues with focused filters for text, team, state, labels, priority, assignee, and project. Results are ordered by recently updated.",
+    async execute(_toolCallId, params: SearchIssuesParams, signal) {
+      const issues = await client.searchIssues(params, signal);
+      return textResult(
+        formatIssueSearch("Linear issue search results", issues),
+        {
+          issues,
+        },
+      );
+    },
+    label: "Linear Search Issues",
+    name: "linear_search_issues",
+    parameters: SearchIssuesParams,
+    promptGuidelines: [
+      "Use linear_search_issues instead of broad Linear API calls; prefer narrow filters and small limits to avoid wasting Linear rate limit and context.",
+    ],
+    promptSnippet: "Search Linear issues with focused filters",
+  });
+
+  pi.registerTool({
+    description:
+      "List Linear issues assigned to and recently created by the authenticated user.",
+    async execute(_toolCallId, params: MyWorkParams, signal) {
+      const work = await client.myWork(params.limit, signal);
+      return textResult(formatMyWork(work), work);
+    },
+    label: "Linear My Work",
+    name: "linear_my_work",
+    parameters: MyWorkParams,
+    promptGuidelines: [
+      "Use linear_my_work when the user asks what Linear work is currently assigned to them or recently created by them.",
+    ],
+    promptSnippet: "List Linear work for the authenticated user",
+  });
+
+  pi.registerTool({
+    description: "List available Linear teams with their keys and UUIDs.",
+    async execute(_toolCallId, _params, signal) {
+      const teams = await client.teams(signal);
+      return textResult(formatTeams(teams), { teams });
+    },
+    label: "Linear List Teams",
+    name: "linear_list_teams",
+    parameters: EmptyParams,
+    promptGuidelines: [
+      "Use linear_list_teams before creating issues if the target Linear team id or key is unclear.",
+    ],
+    promptSnippet: "List Linear teams and their keys/UUIDs",
+  });
+
+  pi.registerTool({
+    description:
+      "List workflow states for a Linear team by team UUID, key, or exact name.",
+    async execute(_toolCallId, params: ListStatesParams, signal) {
+      const states = await client.states(params.team, signal);
+      return textResult(formatStates(params.team, states), { states });
+    },
+    label: "Linear List States",
+    name: "linear_list_states",
+    parameters: ListStatesParams,
+    promptGuidelines: [
+      "Use linear_list_states before updating a Linear issue state unless the workflow state UUID is already known.",
+    ],
+    promptSnippet: "List workflow states for a Linear team",
+  });
+
+  pi.registerTool({
+    description:
+      "Create a Linear issue. Provide a team UUID, key, or exact name, plus title and optional markdown description/metadata.",
+    async execute(_toolCallId, params: CreateIssueParams, signal) {
+      const issue = await client.createIssue(params, signal);
+      return textResult(
+        `Created Linear issue:\n\n${formatIssueSearch("", [issue]).trim()}`,
+        {
+          issue,
+        },
+      );
+    },
+    label: "Linear Create Issue",
+    name: "linear_create_issue",
+    parameters: CreateIssueParams,
+    promptGuidelines: [
+      "Use linear_create_issue when the user asks to file or track work in Linear; ask for confirmation before creating issues if intent is ambiguous.",
+      "When creating Linear issues from coding findings, include concise reproduction context, expected behavior, and relevant file paths in the description.",
+    ],
+    promptSnippet: "Create a Linear issue",
+  });
+
+  pi.registerTool({
+    description:
+      "Update a Linear issue by UUID or identifier. Only provided fields are changed.",
+    async execute(_toolCallId, params: UpdateIssueParams, signal) {
+      const issue = await client.updateIssue(params, signal);
+      return textResult(
+        `Updated Linear issue:\n\n${formatIssueSearch("", [issue]).trim()}`,
+        {
+          issue,
+        },
+      );
+    },
+    label: "Linear Update Issue",
+    name: "linear_update_issue",
+    parameters: UpdateIssueParams,
+    promptGuidelines: [
+      "Use linear_update_issue for explicit user-requested Linear metadata changes. Do not mark work complete unless checks have passed or the user instructs it.",
+    ],
+    promptSnippet: "Update a Linear issue",
+  });
+
+  pi.registerTool({
+    description:
+      "Add a markdown comment to a Linear issue by UUID or identifier.",
+    async execute(_toolCallId, params: CommentIssueParams, signal) {
+      const comment = await client.commentIssue(
+        params.issueId,
+        params.body,
+        signal,
+      );
+      return textResult(
+        `Added Linear comment ${comment.id} to ${params.issueId}.`,
+        {
+          comment,
+        },
+      );
+    },
+    label: "Linear Comment Issue",
+    name: "linear_comment_issue",
+    parameters: CommentIssueParams,
+    promptGuidelines: [
+      "Use linear_comment_issue when the user asks to post an implementation summary, status update, question, or result to a Linear issue.",
+      "Before posting to Linear, keep comments concise and factual; include commands run and whether they passed when reporting implementation work.",
+    ],
+    promptSnippet: "Add a markdown comment to a Linear issue",
+  });
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+export interface LinearUser {
+  displayName?: string | null;
+  email?: string | null;
+  id: string;
+  name?: string | null;
+}
+
+export interface LinearTeam {
+  id: string;
+  key: string;
+  name: string;
+}
+
+export interface LinearState {
+  id: string;
+  name: string;
+  position?: number | null;
+  type?: string | null;
+}
+
+export interface LinearLabel {
+  color?: string | null;
+  id: string;
+  name: string;
+}
+
+export interface LinearProject {
+  id: string;
+  name: string;
+  url?: string | null;
+}
+
+export interface LinearComment {
+  body: string;
+  createdAt: string;
+  id: string;
+  updatedAt?: string | null;
+  user?: LinearUser | null;
+}
+
+export interface LinearIssueSummary {
+  assignee?: LinearUser | null;
+  createdAt: string;
+  delegate?: LinearUser | null;
+  description?: string | null;
+  dueDate?: string | null;
+  estimate?: number | null;
+  id: string;
+  identifier: string;
+  labels?: { nodes: LinearLabel[] };
+  priority?: number | null;
+  priorityLabel?: string | null;
+  project?: LinearProject | null;
+  state?: LinearState | null;
+  team?: LinearTeam | null;
+  title: string;
+  updatedAt: string;
+  url: string;
+}
+
+export interface LinearIssue extends LinearIssueSummary {
+  comments?: { nodes: LinearComment[] };
+  creator?: LinearUser | null;
+}
+
+export type LinearViewer = LinearUser;
+
+export type LinearSetupResult =
+  | { error: string; ok: false }
+  | { ok: true; viewer: LinearViewer };
+
+export interface LinearSearchParams {
+  assigneeEmail?: string;
+  assigneeId?: string;
+  includeArchived?: boolean;
+  labels?: string[];
+  limit?: number;
+  priority?: number;
+  projectName?: string;
+  query?: string;
+  stateName?: string;
+  stateType?:
+    | "backlog"
+    | "canceled"
+    | "completed"
+    | "started"
+    | "triage"
+    | "unstarted";
+  team?: string;
+}
+
+export interface LinearCreateIssueParams {
+  assigneeId?: string;
+  description?: string;
+  dueDate?: string;
+  labelIds?: string[];
+  priority?: number;
+  projectId?: string;
+  stateId?: string;
+  team: string;
+  title: string;
+}
+
+export interface LinearUpdateIssueParams {
+  assigneeId?: string | null;
+  description?: string;
+  dueDate?: string | null;
+  issueId: string;
+  labelIds?: string[];
+  priority?: number | null;
+  projectId?: string | null;
+  stateId?: string;
+  title?: string;
+}