@fink-andreas/pi-linear-tools 0.2.0 → 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',
@@ -613,10 +616,6 @@ async function registerLinearTools(pi) {
           type: 'string',
           description: 'Parent comment ID for reply (for comment)',
         },
-        branch: {
-          type: 'string',
-          description: 'Custom branch name override (for start)',
-        },
         fromRef: {
           type: 'string',
           description: 'Git ref to branch from (default: HEAD, for start)',
@@ -632,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}`);
       }
     },
   });
@@ -677,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}`);
       }
     },
   });
@@ -706,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 executeTeamList(client);
-        default:
-          throw new Error(`Unknown action: ${params.action}`);
+        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;
+        }
+
+        throw new Error(`Linear team operation failed: ${errorMessage}`);
       }
     },
   });
@@ -750,20 +848,15 @@ async function registerLinearTools(pi) {
             type: 'string',
             description: 'Target completion date (ISO 8601 date)',
           },
-          status: {
-            type: 'string',
-            enum: ['backlogged', 'planned', 'inProgress', 'paused', 'completed', 'done', 'cancelled'],
-            description: 'Milestone status',
-          },
         },
         required: ['action'],
         additionalProperties: false,
       },
       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);
@@ -779,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}`);
         }
       },
     });
@@ -787,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) => {
@@ -924,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);
+  }
 }