@fink-andreas/pi-linear-tools 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v0.3.0 (2026-03-22)
+
+Rate limit optimization and crash prevention release.
+
+### Bug Fixes
+- Fixed rate limit crashes by eliminating N+1 API queries (root cause)
+- Added global rate limit tracking to prevent repeated API calls
+- Added comprehensive error handling to prevent extension crashes
+
+### Performance
+- Replaced SDK lazy-loading with optimized GraphQL queries
+- API requests per issue listing: ~251 → 1
+- Listings before hitting rate limit: ~50 → ~5000
+
+### Improvements
+- Reduced default pagination limit (50 → 20) to reduce API load
+- Better user-friendly error messages for rate limit errors
+- Rate limit pre-check before making API calls
+
 ## v0.2.0 (2026-02-28)
 
 OAuth 2.0 authentication and Markdown rendering release.

package/extensions/pi-linear-tools.js

@@ -1,5 +1,5 @@
 import { loadSettings, saveSettings } from '../src/settings.js';
-import { createLinearClient } from '../src/linear-client.js';
+import { createLinearClient, isGloballyRateLimited, markRateLimited } from '../src/linear-client.js';
 import { setQuietMode } from '../src/logger.js';
 import {
   resolveProjectRef,
@@ -502,7 +502,10 @@ function renderMarkdownResult(result, _options, _theme) {
 }
 
 async function registerLinearTools(pi) {
-  if (typeof pi.registerTool !== 'function') return;
+  if (typeof pi.registerTool !== 'function') {
+    console.warn('[pi-linear-tools] pi.registerTool not available');
+    return;
+  }
 
   pi.registerTool({
     name: 'linear_issue',
@@ -628,29 +631,90 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      const client = await createAuthenticatedClient();
-
-      switch (params.action) {
-        case 'list':
-          return executeIssueList(client, params);
-        case 'view':
-          return executeIssueView(client, params);
-        case 'create':
-          return executeIssueCreate(client, params, { resolveDefaultTeam });
-        case 'update':
-          return executeIssueUpdate(client, params);
-        case 'comment':
-          return executeIssueComment(client, params);
-        case 'start':
-          return executeIssueStart(client, params, {
-            gitExecutor: async (branchName, fromRef, onBranchExists) => {
-              return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
-            },
-          });
-        case 'delete':
-          return executeIssueDelete(client, params);
-        default:
-          throw new Error(`Unknown action: ${params.action}`);
+      // Pre-check: skip API calls if we know we're rate limited
+      const { isRateLimited, resetAt } = isGloballyRateLimited();
+      if (isRateLimited) {
+        throw new Error(
+          `Linear API rate limit exceeded (cached).\n\n` +
+          `The rate limit resets at: ${resetAt.toLocaleTimeString()}\n\n` +
+          `Please wait before making more requests.`
+        );
+      }
+
+      try {
+        const client = await createAuthenticatedClient();
+
+        switch (params.action) {
+          case 'list':
+            return await executeIssueList(client, params);
+          case 'view':
+            return await executeIssueView(client, params);
+          case 'create':
+            return await executeIssueCreate(client, params, { resolveDefaultTeam });
+          case 'update':
+            return await executeIssueUpdate(client, params);
+          case 'comment':
+            return await executeIssueComment(client, params);
+          case 'start':
+            return await executeIssueStart(client, params, {
+              gitExecutor: async (branchName, fromRef, onBranchExists) => {
+                return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
+              },
+            });
+          case 'delete':
+            return await executeIssueDelete(client, params);
+          default:
+            throw new Error(`Unknown action: ${params.action}`);
+        }
+      } catch (error) {
+        // Comprehensive error handling - catch ALL errors including SDK's RatelimitedLinearError
+        const errorType = error?.type || '';
+        const errorMessage = String(error?.message || error || 'Unknown error');
+
+        // Rate limit error - provide clear reset time and mark globally
+        if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
+          const resetTimestamp = error?.requestsResetAt || (Date.now() + 3600000);
+          const resetTime = new Date(resetTimestamp).toLocaleTimeString();
+          markRateLimited(resetTimestamp);
+          throw new Error(
+            `Linear API rate limit exceeded.\n\n` +
+            `The rate limit resets at: ${resetTime}\n\n` +
+            `Please wait before making more requests, or reduce the frequency of API calls.`
+          );
+        }
+
+        // Authentication/Forbidden errors (handles SDK's ForbiddenLinearError)
+        if (errorType === 'Forbidden' || errorType === 'AuthenticationError' ||
+          errorMessage.toLowerCase().includes('forbidden') || errorMessage.toLowerCase().includes('unauthorized')) {
+          throw new Error(
+            `Linear API authentication failed: ${errorMessage}\n\n` +
+            `Please check your API key or OAuth token permissions.`
+          );
+        }
+
+        // Network errors (handles SDK's NetworkError)
+        if (errorType === 'NetworkError' || errorMessage.toLowerCase().includes('network')) {
+          throw new Error(
+            `Network error communicating with Linear API.\n\n` +
+            `Please check your internet connection and try again.`
+          );
+        }
+
+        // Internal server errors (handles SDK's InternalError)
+        if (errorType === 'InternalError' || (error?.status >= 500 && error?.status < 600)) {
+          throw new Error(
+            `Linear API server error (${error?.status || 'unknown'}).\n\n` +
+            `Linear may be experiencing issues. Please try again later.`
+          );
+        }
+
+        // Re-throw if already formatted with "Linear API error:"
+        if (errorMessage.includes('Linear API error:')) {
+          throw error;
+        }
+
+        // Wrap unexpected errors with context - NEVER let raw errors propagate
+        throw new Error(`Linear issue operation failed: ${errorMessage}`);
       }
     },
   });
@@ -673,13 +737,32 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      const client = await createAuthenticatedClient();
+      try {
+        const client = await createAuthenticatedClient();
 
-      switch (params.action) {
-        case 'list':
-          return executeProjectList(client);
-        default:
-          throw new Error(`Unknown action: ${params.action}`);
+        switch (params.action) {
+          case 'list':
+            return await executeProjectList(client);
+          default:
+            throw new Error(`Unknown action: ${params.action}`);
+        }
+      } catch (error) {
+        // Comprehensive error handling - catch ALL errors
+        const errorType = error?.type || '';
+        const errorMessage = String(error?.message || error || 'Unknown error');
+
+        if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
+          const resetAt = error?.requestsResetAt
+            ? new Date(error.requestsResetAt).toLocaleTimeString()
+            : 'approximately 1 hour from now';
+          throw new Error(`Linear API rate limit exceeded. Resets at: ${resetAt}. Please wait before retrying.`);
+        }
+
+        if (errorMessage.includes('Linear API error:')) {
+          throw error;
+        }
+
+        throw new Error(`Linear project operation failed: ${errorMessage}`);
       }
     },
   });
@@ -702,13 +785,32 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      const client = await createAuthenticatedClient();
+      try {
+        const client = await createAuthenticatedClient();
+
+        switch (params.action) {
+          case 'list':
+            return await executeTeamList(client);
+          default:
+            throw new Error(`Unknown action: ${params.action}`);
+        }
+      } catch (error) {
+        // Comprehensive error handling - catch ALL errors
+        const errorType = error?.type || '';
+        const errorMessage = String(error?.message || error || 'Unknown error');
+
+        if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
+          const resetAt = error?.requestsResetAt
+            ? new Date(error.requestsResetAt).toLocaleTimeString()
+            : 'approximately 1 hour from now';
+          throw new Error(`Linear API rate limit exceeded. Resets at: ${resetAt}. Please wait before retrying.`);
+        }
+
+        if (errorMessage.includes('Linear API error:')) {
+          throw error;
+        }
 
-      switch (params.action) {
-        case 'list':
-          return executeTeamList(client);
-        default:
-          throw new Error(`Unknown action: ${params.action}`);
+        throw new Error(`Linear team operation failed: ${errorMessage}`);
       }
     },
   });
@@ -752,9 +854,9 @@ async function registerLinearTools(pi) {
       },
       renderResult: renderMarkdownResult,
       async execute(_toolCallId, params) {
-        const client = await createAuthenticatedClient();
-
         try {
+          const client = await createAuthenticatedClient();
+
           switch (params.action) {
             case 'list':
               return await executeMilestoneList(client, params);
@@ -770,7 +872,24 @@ async function registerLinearTools(pi) {
               throw new Error(`Unknown action: ${params.action}`);
           }
         } catch (error) {
-          throw withMilestoneScopeHint(error);
+          // Apply milestone-specific hint, then wrap with operation context
+          const hintError = withMilestoneScopeHint(error);
+          // Comprehensive error handling - catch ALL errors
+          const errorType = error?.type || '';
+          const errorMessage = String(hintError?.message || hintError || 'Unknown error');
+
+          if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
+            const resetAt = error?.requestsResetAt
+              ? new Date(error.requestsResetAt).toLocaleTimeString()
+              : 'approximately 1 hour from now';
+            throw new Error(`Linear API rate limit exceeded. Resets at: ${resetAt}. Please wait before retrying.`);
+          }
+
+          if (errorMessage.includes('Linear API error:')) {
+            throw hintError;
+          }
+
+          throw new Error(`Linear milestone operation failed: ${errorMessage}`);
         }
       },
     });
@@ -778,6 +897,8 @@ async function registerLinearTools(pi) {
 }
 
 export default async function piLinearToolsExtension(pi) {
+  // Safety wrapper: never let extension errors crash pi
+  try {
   pi.registerCommand('linear-tools-config', {
     description: 'Configure pi-linear-tools settings (API key and default team mappings)',
     handler: async (argsText, ctx) => {
@@ -915,4 +1036,8 @@ export default async function piLinearToolsExtension(pi) {
   });
 
   await registerLinearTools(pi);
+  } catch (error) {
+    // Safety: never let extension initialization crash pi
+    console.error('[pi-linear-tools] Extension initialization failed:', error?.message || error);
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Pi extension with Linear SDK tools and configuration commands",
   "type": "module",
   "engines": {

package/src/handlers.js

@@ -27,8 +27,9 @@ import {
   updateProjectMilestone,
   deleteProjectMilestone,
   deleteIssue,
+  withHandlerErrorHandling,
 } from './linear.js';
-import { debug } from './logger.js';
+import { debug, warn } from './logger.js';
 
 function toTextResult(text, details = {}) {
   return {
@@ -128,57 +129,59 @@ async function startGitBranch(branchName, fromRef = 'HEAD', onBranchExists = 'sw
  * List issues in a project
  */
 export async function executeIssueList(client, params) {
-  let projectRef = params.project;
-  if (!projectRef) {
-    projectRef = process.cwd().split('/').pop();
-  }
+  return withHandlerErrorHandling(async () => {
+    let projectRef = params.project;
+    if (!projectRef) {
+      projectRef = process.cwd().split('/').pop();
+    }
 
-  const resolved = await resolveProjectRef(client, projectRef);
+    const resolved = await resolveProjectRef(client, projectRef);
 
-  let assigneeId = null;
-  if (params.assignee === 'me') {
-    const viewer = await client.viewer;
-    assigneeId = viewer.id;
-  }
-
-  const { issues, truncated } = await fetchIssuesByProject(client, resolved.id, params.states || null, {
-    assigneeId,
-    limit: params.limit || 50,
-  });
+    let assigneeId = null;
+    if (params.assignee === 'me') {
+      const viewer = await client.viewer;
+      assigneeId = viewer.id;
+    }
 
-  if (issues.length === 0) {
-    return toTextResult(`No issues found in project "${resolved.name}"`, {
-      projectId: resolved.id,
-      projectName: resolved.name,
-      issueCount: 0,
+    const { issues, truncated } = await fetchIssuesByProject(client, resolved.id, params.states || null, {
+      assigneeId,
+      limit: params.limit || 20,
     });
-  }
 
-  const lines = [`## Issues in project "${resolved.name}" (${issues.length}${truncated ? '+' : ''})\n`];
+    if (issues.length === 0) {
+      return toTextResult(`No issues found in project "${resolved.name}"`, {
+        projectId: resolved.id,
+        projectName: resolved.name,
+        issueCount: 0,
+      });
+    }
 
-  for (const issue of issues) {
-    const stateLabel = issue.state?.name || 'Unknown';
-    const assigneeLabel = issue.assignee?.displayName || 'Unassigned';
-    const priorityLabel = issue.priority !== undefined && issue.priority !== null
-      ? ['None', 'Urgent', 'High', 'Medium', 'Low'][issue.priority] || `P${issue.priority}`
-      : null;
+    const lines = [`## Issues in project "${resolved.name}" (${issues.length}${truncated ? '+' : ''})\n`];
 
-    const metaParts = [`[${stateLabel}]`, `@${assigneeLabel}`];
-    if (priorityLabel) metaParts.push(priorityLabel);
+    for (const issue of issues) {
+      const stateLabel = issue.state?.name || 'Unknown';
+      const assigneeLabel = issue.assignee?.displayName || 'Unassigned';
+      const priorityLabel = issue.priority !== undefined && issue.priority !== null
+        ? ['None', 'Urgent', 'High', 'Medium', 'Low'][issue.priority] || `P${issue.priority}`
+        : null;
 
-    lines.push(`- **${issue.identifier}**: ${issue.title} _${metaParts.join(' ')}_`);
-  }
+      const metaParts = [`[${stateLabel}]`, `@${assigneeLabel}`];
+      if (priorityLabel) metaParts.push(priorityLabel);
 
-  if (truncated) {
-    lines.push('\n_Results may be truncated. Use limit parameter to fetch more._');
-  }
+      lines.push(`- **${issue.identifier}**: ${issue.title} _${metaParts.join(' ')}_`);
+    }
 
-  return toTextResult(lines.join('\n'), {
-    projectId: resolved.id,
-    projectName: resolved.name,
-    issueCount: issues.length,
-    truncated,
-  });
+    if (truncated) {
+      lines.push('\n_Results may be truncated. Use limit parameter to fetch more._');
+    }
+
+    return toTextResult(lines.join('\n'), {
+      projectId: resolved.id,
+      projectName: resolved.name,
+      issueCount: issues.length,
+      truncated,
+    });
+  }, 'executeIssueList');
 }
 
 /**

package/src/linear-client.js

@@ -11,8 +11,88 @@ import { debug, warn, error as logError } from './logger.js';
 /** @type {Function|null} Test-only client factory override */
 let _testClientFactory = null;
 
+/** @type {Map<string, {remaining: number, resetAt: number}>} Per-client rate limit tracking */
+const rateLimitTracker = new Map();
+
+/** Track globally if we've detected a rate limit error */
+let globalRateLimited = false;
+let globalRateLimitResetAt = null;
+
+/**
+ * Check if we know we're rate limited and should skip API calls
+ * @returns {{isRateLimited: boolean, resetAt: Date|null}}
+ */
+export function isGloballyRateLimited() {
+  if (!globalRateLimited || !globalRateLimitResetAt) {
+    return { isRateLimited: false, resetAt: null };
+  }
+
+  // Check if rate limit window has passed
+  if (Date.now() >= globalRateLimitResetAt) {
+    globalRateLimited = false;
+    globalRateLimitResetAt = null;
+    return { isRateLimited: false, resetAt: null };
+  }
+
+  return { isRateLimited: true, resetAt: new Date(globalRateLimitResetAt) };
+}
+
 /**
- * Create a Linear SDK client
+ * Mark that we've hit the rate limit
+ * @param {number} resetAt - Reset timestamp in milliseconds
+ */
+export function markRateLimited(resetAt) {
+  globalRateLimited = true;
+  globalRateLimitResetAt = resetAt;
+  warn('[pi-linear-tools] Rate limit hit - will skip API calls until reset', {
+    resetAt: new Date(resetAt).toLocaleTimeString(),
+  });
+}
+
+/**
+ * Extract rate limit info from SDK client response
+ * The Linear SDK stores response metadata on the client after requests
+ * @param {LinearClient} client - Linear SDK client
+ * @returns {{remaining: number|null, resetAt: number|null, resetTime: string|null}}
+ */
+export function getClientRateLimit(client) {
+  // Try to get from tracker first
+  const trackerData = rateLimitTracker.get(client.apiKey || 'default');
+  if (trackerData) {
+    return {
+      remaining: trackerData.remaining,
+      resetAt: trackerData.resetAt,
+      resetTime: trackerData.resetAt ? new Date(trackerData.resetAt).toLocaleTimeString() : null,
+    };
+  }
+
+  return { remaining: null, resetAt: null, resetTime: null };
+}
+
+/**
+ * Check and warn about low rate limit for a client
+ * Call this after making API requests to check if limits are getting low
+ * @param {LinearClient} client - Linear SDK client
+ * @returns {boolean} True if warning was issued
+ */
+export function checkAndWarnRateLimit(client) {
+  const { remaining, resetTime } = getClientRateLimit(client);
+
+  if (remaining !== null && remaining <= 500) {
+    const usagePercent = Math.round(((5000 - remaining) / 5000) * 100);
+    warn(`Linear API rate limit running low: ${remaining} requests remaining (~${usagePercent}% used). Resets at ${resetTime}`, {
+      remaining,
+      resetTime,
+      usagePercent,
+    });
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Create a Linear SDK client with rate limit tracking
  *
  * Supports two authentication methods:
  * 1. API Key: Pass as string or { apiKey: '...' }
@@ -30,18 +110,22 @@ export function createLinearClient(auth) {
   }
 
   let clientConfig;
+  let apiKey = null;
 
   // Handle different input formats
   if (typeof auth === 'string') {
     // Legacy: API key passed as string
     clientConfig = { apiKey: auth };
+    apiKey = auth;
   } else if (typeof auth === 'object' && auth !== null) {
     // Object format: { apiKey: '...' } or { accessToken: '...' }
     if (auth.accessToken) {
       clientConfig = { apiKey: auth.accessToken };
+      apiKey = auth.accessToken;
       debug('Creating Linear client with OAuth access token');
     } else if (auth.apiKey) {
       clientConfig = { apiKey: auth.apiKey };
+      apiKey = auth.apiKey;
       debug('Creating Linear client with API key');
     } else {
       throw new Error(
@@ -54,7 +138,54 @@ export function createLinearClient(auth) {
     );
   }
 
-  return new LinearClient(clientConfig);
+  const client = new LinearClient(clientConfig);
+
+  // Initialize rate limit tracking for this client
+  const trackerKey = apiKey || 'default';
+  if (!rateLimitTracker.has(trackerKey)) {
+    rateLimitTracker.set(trackerKey, { remaining: 5000, resetAt: Date.now() + 3600000 });
+  }
+
+  // Wrap the rawRequest to capture rate limit headers
+  // rawRequest is on client.client (internal GraphQL client)
+  const originalRawRequest = client.client.rawRequest.bind(client.client);
+  client.client.rawRequest = async function wrappedRawRequest(query, variables, requestHeaders) {
+    const response = await originalRawRequest(query, variables, requestHeaders);
+
+    // Extract rate limit headers from response
+    if (response.headers) {
+      const remaining = response.headers.get('X-RateLimit-Requests-Remaining');
+      const resetAt = response.headers.get('X-RateLimit-Requests-Reset');
+
+      if (remaining !== null) {
+        const tracker = rateLimitTracker.get(trackerKey);
+        if (tracker) {
+          tracker.remaining = parseInt(remaining, 10);
+        }
+      }
+      if (resetAt !== null) {
+        const tracker = rateLimitTracker.get(trackerKey);
+        if (tracker) {
+          tracker.resetAt = parseInt(resetAt, 10);
+        }
+      }
+    }
+
+    // Check if we should warn about low rate limits
+    const tracker = rateLimitTracker.get(trackerKey);
+    if (tracker && tracker.remaining <= 500 && tracker.remaining > 0) {
+      const usagePercent = Math.round(((5000 - tracker.remaining) / 5000) * 100);
+      warn(`Linear API rate limit running low: ${tracker.remaining} requests remaining (~${usagePercent}% used). Resets at ${new Date(tracker.resetAt).toLocaleTimeString()}`, {
+        remaining: tracker.remaining,
+        resetTime: new Date(tracker.resetAt).toLocaleTimeString(),
+        usagePercent,
+      });
+    }
+
+    return response;
+  };
+
+  return client;
 }
 
 /**