@alasano/pi-linear 0.0.1

package/README.md

@@ -0,0 +1,181 @@
+# pi-linear
+
+![pi-linear screenshot](assets/screenshot.png)
+
+Linear integration for [pi](https://pi.dev) with 55+ tools covering issues, projects, documents, initiatives, comments, relations, and more. Includes multi-workspace auth and a per-tool settings overlay.
+
+## Prerequisites
+
+You need a Linear API key. To create one:
+
+1. Go to **Linear Settings > Account > Security & Access > API**
+2. Click **Create key** and give it a name (e.g. "pi")
+3. Under **Permissions**, select **Only select permissions** with **Read** and **Write** enabled. Leave **Admin** unchecked.
+4. Under **Team access**, choose **All teams you have access to** or scope to specific teams if you prefer
+5. Click **Create** and copy the key
+
+## Install
+
+```bash
+pi install npm:@alasano/pi-linear
+```
+
+## Authentication
+
+The extension auto-detects the `LINEAR_API_KEY` environment variable if set globally. No setup needed in that case.
+
+For multi-workspace support or if you don't have the env var, use the `/linear-auth` command:
+
+| Command                      | Description                                              |
+| ---------------------------- | -------------------------------------------------------- |
+| `/linear-auth add <name>`    | Add a workspace with an API key (prompts for key)        |
+| `/linear-auth remove <name>` | Remove a workspace (shows selector if name omitted)      |
+| `/linear-auth switch <name>` | Switch active workspace (shows selector if name omitted) |
+| `/linear-auth status`        | Show current auth source and configured workspaces       |
+| `/linear-auth`               | Same as status                                           |
+
+When you add your first workspace, it becomes active automatically. Adding a second workspace prompts you to switch. After a `/reload` with two or more workspaces configured, the agent gets a `linear_switch_workspace` tool and can switch between them when asked.
+
+Auth resolution order:
+
+1. Active stored workspace (if any workspaces are configured)
+2. `LINEAR_API_KEY` environment variable (fallback when no workspaces configured)
+3. Interactive prompt (asks you to set up a key)
+
+Credentials are stored at `~/.pi/agent/state/extensions/linear/credentials.json`.
+
+## Tool settings
+
+Run `/linear-settings` to open an overlay where you can enable or disable tools by category or individually. Disabled tools are removed from the LLM's context entirely. Preferences persist across sessions.
+
+## Tools (55)
+
+### Issues
+
+| Tool                     | Description                                                        |
+| ------------------------ | ------------------------------------------------------------------ |
+| `linear_list_issues`     | List issues with filters, pagination, and sort                     |
+| `linear_get_issue`       | Get full issue details by identifier (ENG-123) or id               |
+| `linear_create_issue`    | Create an issue with full IssueCreateInput support                 |
+| `linear_update_issue`    | Update an issue with full IssueUpdateInput support                 |
+| `linear_delete_issue`    | Delete an issue (admins can permanently delete)                    |
+| `linear_archive_issue`   | Archive or trash an issue                                          |
+| `linear_unarchive_issue` | Restore an archived issue                                          |
+| `linear_search_issues`   | Search issues by text, with optional comment search and team boost |
+
+### Issue Labels
+
+| Tool                        | Description                        |
+| --------------------------- | ---------------------------------- |
+| `linear_list_issue_labels`  | List issue labels with team filter |
+| `linear_create_issue_label` | Create an issue label              |
+| `linear_update_issue_label` | Update an issue label              |
+| `linear_delete_issue_label` | Delete an issue label              |
+
+### Issue Statuses
+
+| Tool                         | Description                           |
+| ---------------------------- | ------------------------------------- |
+| `linear_list_issue_statuses` | List workflow states (issue statuses) |
+
+### Issue Relations
+
+| Tool                           | Description                                             |
+| ------------------------------ | ------------------------------------------------------- |
+| `linear_list_issue_relations`  | List issue relations                                    |
+| `linear_create_issue_relation` | Create a relation (blocks, duplicate, related, similar) |
+| `linear_update_issue_relation` | Update a relation                                       |
+| `linear_delete_issue_relation` | Delete a relation                                       |
+
+### Projects
+
+| Tool                       | Description                                      |
+| -------------------------- | ------------------------------------------------ |
+| `linear_list_projects`     | List projects with filters, pagination, and sort |
+| `linear_get_project`       | Get full project details by id                   |
+| `linear_save_project`      | Create or update a project                       |
+| `linear_delete_project`    | Delete a project                                 |
+| `linear_archive_project`   | Archive or trash a project                       |
+| `linear_unarchive_project` | Restore an archived project                      |
+
+### Project Labels
+
+| Tool                          | Description            |
+| ----------------------------- | ---------------------- |
+| `linear_list_project_labels`  | List project labels    |
+| `linear_create_project_label` | Create a project label |
+| `linear_update_project_label` | Update a project label |
+| `linear_delete_project_label` | Delete a project label |
+
+### Project Relations
+
+| Tool                             | Description               |
+| -------------------------------- | ------------------------- |
+| `linear_list_project_relations`  | List project relations    |
+| `linear_create_project_relation` | Create a project relation |
+| `linear_update_project_relation` | Update a project relation |
+| `linear_delete_project_relation` | Delete a project relation |
+
+### Documents
+
+| Tool                        | Description                                |
+| --------------------------- | ------------------------------------------ |
+| `linear_list_documents`     | List documents with filters and pagination |
+| `linear_get_document`       | Get full document details by id            |
+| `linear_create_document`    | Create a document                          |
+| `linear_update_document`    | Update a document                          |
+| `linear_delete_document`    | Delete a document                          |
+| `linear_unarchive_document` | Restore an archived document               |
+
+### Comments
+
+| Tool                    | Description                                        |
+| ----------------------- | -------------------------------------------------- |
+| `linear_list_comments`  | List comments with filters and pagination          |
+| `linear_create_comment` | Create a comment on an issue, project update, etc. |
+| `linear_update_comment` | Update a comment                                   |
+| `linear_delete_comment` | Delete a comment                                   |
+
+### Initiatives
+
+| Tool                          | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
+| `linear_list_initiatives`     | List initiatives with filters, pagination, and sort |
+| `linear_get_initiative`       | Get full initiative details by id                   |
+| `linear_save_initiative`      | Create or update an initiative                      |
+| `linear_delete_initiative`    | Delete an initiative                                |
+| `linear_archive_initiative`   | Archive an initiative                               |
+| `linear_unarchive_initiative` | Restore an archived initiative                      |
+
+### Milestones
+
+| Tool                      | Description                  |
+| ------------------------- | ---------------------------- |
+| `linear_list_milestones`  | List project milestones      |
+| `linear_get_milestone`    | Get milestone details by id  |
+| `linear_save_milestone`   | Create or update a milestone |
+| `linear_delete_milestone` | Delete a milestone           |
+
+### Teams
+
+| Tool                | Description                     |
+| ------------------- | ------------------------------- |
+| `linear_list_teams` | List teams with workflow states |
+| `linear_get_team`   | Get team details by id          |
+
+### Users
+
+| Tool                | Description            |
+| ------------------- | ---------------------- |
+| `linear_list_users` | List users             |
+| `linear_get_user`   | Get user details by id |
+
+### Workspaces
+
+| Tool                      | Description                                                 |
+| ------------------------- | ----------------------------------------------------------- |
+| `linear_switch_workspace` | Switch active workspace (only available with 2+ workspaces) |
+
+## Requirements
+
+- Pi interactive mode (settings overlay uses the widget API)

package/extensions/client.ts

@@ -0,0 +1,291 @@
+import type { ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { LinearGraphQLError, LinearIssue } from './types';
+import { asString } from './util';
+import { ISSUE_SELECTION } from './selections';
+
+const LINEAR_GRAPHQL_ENDPOINT = 'https://api.linear.app/graphql';
+const IDENTIFIER_PATTERN = /^([A-Z][A-Z0-9]*)-(\d+)$/i;
+
+export type WorkspaceCredentials = {
+  activeWorkspace: string | null;
+  workspaces: Record<string, { apiKey: string }>;
+};
+
+function emptyCredentials(): WorkspaceCredentials {
+  return { activeWorkspace: null, workspaces: {} };
+}
+
+export function getCredentialFilePath() {
+  const piDir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), '.pi', 'agent');
+  return path.join(piDir, 'extensions', 'linear', 'credentials.json');
+}
+
+export async function readCredentials(): Promise<WorkspaceCredentials> {
+  const filePath = getCredentialFilePath();
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (
+      !parsed ||
+      typeof parsed !== 'object' ||
+      !parsed.workspaces ||
+      typeof parsed.workspaces !== 'object'
+    ) {
+      return emptyCredentials();
+    }
+    const activeWorkspace =
+      typeof parsed.activeWorkspace === 'string' ? parsed.activeWorkspace : null;
+    const workspaces: Record<string, { apiKey: string }> = {};
+    for (const [name, entry] of Object.entries(parsed.workspaces)) {
+      if (
+        entry &&
+        typeof entry === 'object' &&
+        'apiKey' in entry &&
+        typeof (entry as { apiKey: unknown }).apiKey === 'string'
+      ) {
+        workspaces[name] = { apiKey: (entry as { apiKey: string }).apiKey };
+      }
+    }
+    return { activeWorkspace, workspaces };
+  } catch {
+    return emptyCredentials();
+  }
+}
+
+export async function writeCredentials(creds: WorkspaceCredentials): Promise<void> {
+  const filePath = getCredentialFilePath();
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(creds, null, 2), {
+    mode: 0o600,
+  });
+  await fs.chmod(filePath, 0o600).catch(() => undefined);
+}
+
+export function getActiveApiKey(creds: WorkspaceCredentials): string | undefined {
+  if (!creds.activeWorkspace) return undefined;
+  return creds.workspaces[creds.activeWorkspace]?.apiKey;
+}
+
+export async function addWorkspace(name: string, apiKey: string): Promise<WorkspaceCredentials> {
+  const creds = await readCredentials();
+  creds.workspaces[name] = { apiKey };
+  if (!creds.activeWorkspace) {
+    creds.activeWorkspace = name;
+  }
+  await writeCredentials(creds);
+  return creds;
+}
+
+export async function removeWorkspace(name: string): Promise<WorkspaceCredentials> {
+  const creds = await readCredentials();
+  delete creds.workspaces[name];
+  if (creds.activeWorkspace === name) {
+    const remaining = Object.keys(creds.workspaces);
+    creds.activeWorkspace = remaining[0] ?? null;
+  }
+  await writeCredentials(creds);
+  return creds;
+}
+
+export async function switchWorkspace(name: string): Promise<WorkspaceCredentials> {
+  const creds = await readCredentials();
+  if (!creds.workspaces[name]) {
+    throw new Error(`Workspace "${name}" does not exist.`);
+  }
+  creds.activeWorkspace = name;
+  await writeCredentials(creds);
+  return creds;
+}
+
+export function listWorkspaceNames(creds: WorkspaceCredentials): string[] {
+  return Object.keys(creds.workspaces);
+}
+
+export function getActiveWorkspaceName(creds: WorkspaceCredentials): string | null {
+  return creds.activeWorkspace;
+}
+
+export async function resolveApiKey(
+  ctx: ExtensionContext,
+  options?: { promptIfMissing?: boolean },
+): Promise<{ apiKey?: string; source: 'env' | 'workspace' | 'none' }> {
+  const creds = await readCredentials();
+  const workspaceKey = getActiveApiKey(creds);
+  if (workspaceKey) return { apiKey: workspaceKey, source: 'workspace' };
+
+  const envApiKey = asString(process.env.LINEAR_API_KEY);
+  if (envApiKey) return { apiKey: envApiKey, source: 'env' };
+
+  const promptIfMissing = options?.promptIfMissing ?? true;
+  if (promptIfMissing && ctx.hasUI) {
+    const shouldSetKey = await ctx.ui.confirm(
+      'Linear API key required',
+      'No configured workspace or LINEAR_API_KEY env var found. Would you like to set one now?',
+    );
+    if (!shouldSetKey) return { source: 'none' };
+
+    const nameInput = await ctx.ui.input('Workspace name', 'my-workspace');
+    const name = asString(nameInput);
+    if (!name) return { source: 'none' };
+
+    const keyInput = await ctx.ui.input('Linear API key', 'lin_api_...');
+    const apiKey = asString(keyInput);
+    if (!apiKey) return { source: 'none' };
+
+    await addWorkspace(name, apiKey);
+    ctx.ui.notify(`Workspace "${name}" saved and set as active`, 'info');
+    return { apiKey, source: 'workspace' };
+  }
+
+  return { source: 'none' };
+}
+
+export async function linearGraphQL<TData>(
+  apiKey: string,
+  query: string,
+  variables: Record<string, unknown>,
+  signal?: AbortSignal,
+): Promise<TData> {
+  const response = await fetch(LINEAR_GRAPHQL_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: apiKey,
+    },
+    body: JSON.stringify({ query, variables }),
+    signal,
+  });
+
+  const body = (await response.json()) as {
+    data?: TData;
+    errors?: LinearGraphQLError[];
+  };
+
+  if (!response.ok) {
+    const message =
+      body.errors?.map((error) => error.message).join('; ') ||
+      `${response.status} ${response.statusText}`;
+    throw new Error(`Linear API request failed: ${message}`);
+  }
+
+  if (body.errors?.length) {
+    throw new Error(
+      `Linear GraphQL error: ${body.errors.map((error) => error.message).join('; ')}`,
+    );
+  }
+
+  if (!body.data) {
+    throw new Error('Linear GraphQL response did not include data.');
+  }
+
+  return body.data;
+}
+
+export function parseIdentifier(issueRef: string): { teamKey: string; number: number } | undefined {
+  const match = issueRef.trim().match(IDENTIFIER_PATTERN);
+  if (!match) return undefined;
+
+  return {
+    teamKey: match[1]!.toUpperCase(),
+    number: Number(match[2]!),
+  };
+}
+
+export async function fetchIssueByIdentifier(
+  apiKey: string,
+  identifier: string,
+  signal?: AbortSignal,
+): Promise<LinearIssue | undefined> {
+  const parsed = parseIdentifier(identifier);
+  if (!parsed) return undefined;
+
+  const data = await linearGraphQL<{ issues: { nodes: LinearIssue[] } }>(
+    apiKey,
+    `query GetIssueByIdentifier($teamKey: String!, $number: Float!) {
+      issues(
+        first: 1
+        filter: {
+          team: { key: { eq: $teamKey } }
+          number: { eq: $number }
+        }
+      ) {
+        nodes {
+          ${ISSUE_SELECTION}
+        }
+      }
+    }`,
+    {
+      teamKey: parsed.teamKey,
+      number: parsed.number,
+    },
+    signal,
+  );
+
+  return data.issues.nodes[0];
+}
+
+export async function resolveIssueId(
+  apiKey: string,
+  issueRef: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const identifierIssue = await fetchIssueByIdentifier(apiKey, issueRef, signal);
+  if (identifierIssue?.id) return identifierIssue.id;
+
+  return issueRef.trim();
+}
+
+export async function resolveTeamId(
+  apiKey: string,
+  options: { teamId?: string; teamKey?: string },
+  signal?: AbortSignal,
+): Promise<string> {
+  if (options.teamId?.trim()) {
+    return options.teamId.trim();
+  }
+
+  const teamKey = options.teamKey?.trim();
+  if (!teamKey) {
+    throw new Error('Either teamId or teamKey must be provided.');
+  }
+
+  const data = await linearGraphQL<{ teams: { nodes: Array<{ id: string }> } }>(
+    apiKey,
+    `query ResolveTeam($teamKey: String!) {
+      teams(first: 1, filter: { key: { eq: $teamKey } }) {
+        nodes {
+          id
+        }
+      }
+    }`,
+    { teamKey },
+    signal,
+  );
+
+  const teamId = data.teams.nodes[0]?.id;
+  if (!teamId) {
+    throw new Error(`Linear team not found for key: ${teamKey}`);
+  }
+
+  return teamId;
+}
+
+export async function withLinearAuth<T>(
+  ctx: ExtensionContext,
+  signal: AbortSignal | undefined,
+  handler: (apiKey: string) => Promise<T>,
+): Promise<T> {
+  const { apiKey } = await resolveApiKey(ctx);
+  if (!apiKey) {
+    throw new Error('Missing Linear API key. Set LINEAR_API_KEY or run /linear-auth.');
+  }
+
+  if (signal?.aborted) {
+    throw new Error('Request cancelled.');
+  }
+
+  return handler(apiKey);
+}

package/extensions/index.ts

@@ -0,0 +1,214 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import {
+  readCredentials,
+  addWorkspace,
+  removeWorkspace,
+  switchWorkspace,
+  listWorkspaceNames,
+  getActiveWorkspaceName,
+  resolveApiKey,
+} from './client';
+import { asString } from './util';
+import { teamTools } from './tools/teams';
+import { userTools } from './tools/users';
+import { issueStatusTools } from './tools/issue-statuses';
+import { projectLabelTools } from './tools/project-labels';
+import { milestoneTools } from './tools/milestones';
+import { commentTools } from './tools/comments';
+import { documentTools } from './tools/documents';
+import { initiativeTools } from './tools/initiatives';
+import { issueLabelTools } from './tools/issue-labels';
+import { projectTools } from './tools/projects';
+import { issueTools } from './tools/issues';
+import { issueRelationTools } from './tools/issue-relations';
+import { projectRelationTools } from './tools/project-relations';
+import { workspaceTools } from './tools/workspaces';
+import { registerLinearSettings } from './settings';
+
+export default async function linearExtension(pi: ExtensionAPI) {
+  pi.registerCommand('linear-auth', {
+    description: 'Manage Linear workspace auth (usage: /linear-auth [add|remove|switch|status])',
+    handler: async (args, ctx) => {
+      const parts = args.trim().split(/\s+/);
+      const subcommand = parts[0]?.toLowerCase() || '';
+      const name = parts.slice(1).join(' ').trim();
+
+      switch (subcommand) {
+        case 'add': {
+          const workspaceName =
+            asString(name) || asString(await ctx.ui.input('Workspace name', 'my-workspace'));
+          if (!workspaceName) {
+            ctx.ui.notify('No workspace name provided', 'warning');
+            return;
+          }
+
+          const keyInput = await ctx.ui.input('Linear API key', 'lin_api_...');
+          const apiKey = asString(keyInput);
+          if (!apiKey) {
+            ctx.ui.notify('No API key provided', 'warning');
+            return;
+          }
+
+          const credsBefore = await readCredentials();
+          const countBefore = Object.keys(credsBefore.workspaces).length;
+          const isFirst = countBefore === 0;
+
+          await addWorkspace(workspaceName, apiKey);
+
+          if (isFirst) {
+            ctx.ui.notify(`Workspace "${workspaceName}" saved and set as active`, 'info');
+          } else {
+            const shouldSwitch = await ctx.ui.confirm(
+              'Switch workspace',
+              `Switch to "${workspaceName}" now?`,
+            );
+            if (shouldSwitch) {
+              await switchWorkspace(workspaceName);
+              ctx.ui.notify(`Switched to workspace "${workspaceName}"`, 'info');
+            }
+
+            if (countBefore === 1) {
+              ctx.ui.notify('Workspace added. Run /reload to enable workspace switching.', 'info');
+            } else {
+              ctx.ui.notify('Workspace added.', 'info');
+            }
+          }
+          return;
+        }
+
+        case 'remove': {
+          const creds = await readCredentials();
+          const names = listWorkspaceNames(creds);
+          if (names.length === 0) {
+            ctx.ui.notify('No workspaces configured', 'warning');
+            return;
+          }
+
+          const rawSelection =
+            asString(name) ||
+            (await ctx.ui.select(
+              'Select workspace to remove',
+              names.map((n) => (n === creds.activeWorkspace ? `${n} (active)` : n)),
+            ));
+          const workspaceName = rawSelection?.replace(/ \(active\)$/, '');
+          if (!workspaceName) {
+            ctx.ui.notify('No workspace selected', 'warning');
+            return;
+          }
+
+          if (!creds.workspaces[workspaceName]) {
+            ctx.ui.notify(`Workspace "${workspaceName}" not found`, 'warning');
+            return;
+          }
+
+          const countBefore = names.length;
+          const updated = await removeWorkspace(workspaceName);
+
+          if (creds.activeWorkspace === workspaceName && updated.activeWorkspace) {
+            ctx.ui.notify(
+              `Removed "${workspaceName}". Switched to "${updated.activeWorkspace}".`,
+              'info',
+            );
+          } else {
+            ctx.ui.notify(`Removed workspace "${workspaceName}"`, 'info');
+          }
+
+          if (countBefore === 2) {
+            ctx.ui.notify('Workspace removed. Run /reload to update workspace tools.', 'info');
+          }
+          return;
+        }
+
+        case 'switch': {
+          const creds = await readCredentials();
+          const names = listWorkspaceNames(creds);
+          if (names.length === 0) {
+            ctx.ui.notify('No workspaces configured', 'warning');
+            return;
+          }
+
+          const rawSelection =
+            asString(name) ||
+            (await ctx.ui.select(
+              'Select workspace',
+              names.map((n) => (n === creds.activeWorkspace ? `${n} (active)` : n)),
+            ));
+          const workspaceName = rawSelection?.replace(/ \(active\)$/, '');
+          if (!workspaceName) {
+            ctx.ui.notify('No workspace selected', 'warning');
+            return;
+          }
+
+          if (!creds.workspaces[workspaceName]) {
+            ctx.ui.notify(`Workspace "${workspaceName}" not found`, 'warning');
+            return;
+          }
+
+          await switchWorkspace(workspaceName);
+          ctx.ui.notify(`Active workspace: ${workspaceName}`, 'info');
+          return;
+        }
+
+        case 'status':
+        case '': {
+          const creds = await readCredentials();
+          const { source } = await resolveApiKey(ctx, {
+            promptIfMissing: false,
+          });
+          const names = listWorkspaceNames(creds);
+          const active = getActiveWorkspaceName(creds);
+
+          let sourceLabel: string;
+          if (source === 'workspace') {
+            sourceLabel = `workspace: ${active}`;
+          } else if (source === 'env') {
+            sourceLabel = 'env: LINEAR_API_KEY';
+          } else {
+            sourceLabel = 'none';
+          }
+
+          const lines = [`Auth source: ${sourceLabel}`];
+          if (names.length > 0) {
+            lines.push(
+              `Workspaces: ${names.map((n) => (n === active ? `${n} (active)` : n)).join(', ')}`,
+            );
+          } else {
+            lines.push('No workspaces configured');
+          }
+
+          ctx.ui.notify(lines.join('\n'), source === 'none' ? 'warning' : 'info');
+          return;
+        }
+
+        default: {
+          ctx.ui.notify('Usage: /linear-auth [add|remove|switch|status]', 'warning');
+        }
+      }
+    },
+  });
+
+  const creds = await readCredentials();
+
+  const allTools = [
+    ...teamTools(),
+    ...userTools(),
+    ...issueStatusTools(),
+    ...projectLabelTools(),
+    ...milestoneTools(),
+    ...commentTools(),
+    ...documentTools(),
+    ...initiativeTools(),
+    ...issueLabelTools(),
+    ...projectTools(),
+    ...issueTools(),
+    ...issueRelationTools(),
+    ...projectRelationTools(),
+    ...workspaceTools(creds),
+  ];
+
+  for (const tool of allTools) {
+    pi.registerTool(tool);
+  }
+
+  registerLinearSettings(pi);
+}