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

package/src/auth/token-refresh.js

@@ -133,25 +133,23 @@ const refreshManager = new TokenRefreshManager();
  * @returns {Promise<string>} New access token
  * @throws {Error} If refresh fails
  */
-export async function refreshTokens(refreshToken) {
+async function refreshTokens(refreshToken) {
   return refreshManager.refresh(refreshToken);
 }
 
 /**
- * Check if a token refresh is currently in progress
+ * Check if a token refresh is currently in progress (internal)
  *
  * @returns {boolean} True if a refresh is in progress
  */
-export function isRefreshing() {
+function isRefreshing() {
   return refreshManager.isRefreshInProgress();
 }
 
 /**
- * Reset the token refresh manager
- *
- * This is mainly for testing purposes.
+ * Reset the token refresh manager (internal, for testing)
  */
-export function resetRefreshManager() {
+function resetRefreshManager() {
   refreshManager.reset();
 }
 

package/src/cli.js

@@ -24,6 +24,7 @@ import {
   executeMilestoneUpdate,
   executeMilestoneDelete,
 } from './handlers.js';
+import { withMilestoneScopeHint } from './error-hints.js';
 
 // ===== ARGUMENT PARSING =====
 
@@ -67,19 +68,6 @@ function parseBoolean(value) {
   return undefined;
 }
 
-function withMilestoneScopeHint(error) {
-  const message = String(error?.message || error || 'Unknown error');
-
-  if (/invalid scope/i.test(message) && /write/i.test(message)) {
-    return new Error(
-      `${message}\nHint: Milestone create/update/delete require Linear write scope. ` +
-      `Use API key auth: pi-linear-tools config --api-key <key>`
-    );
-  }
-
-  return error;
-}
-
 // ===== AUTH RESOLUTION =====
 
 let cachedApiKey = null;

package/src/error-hints.js

@@ -0,0 +1,24 @@
+/**
+ * Error hint utilities
+ *
+ * Provides helpful hints for common error scenarios.
+ */
+
+/**
+ * Wraps errors related to milestone operations with helpful scope hints
+ *
+ * @param {Error} error - The error to wrap
+ * @returns {Error} The original error or a new error with additional hint
+ */
+export function withMilestoneScopeHint(error) {
+  const message = String(error?.message || error || 'Unknown error');
+
+  if (/invalid scope/i.test(message) && /write/i.test(message)) {
+    return new Error(
+      `${message}\nHint: Milestone create/update/delete require Linear write scope. ` +
+      `Use API key auth for milestone management: /linear-tools-config --api-key <key>`
+    );
+  }
+
+  return error;
+}

package/src/handlers.js

@@ -5,7 +5,6 @@
  * All handlers are pure functions that accept a LinearClient and parameters.
  */
 
-import { createLinearClient } from './linear-client.js';
 import {
   prepareIssueStart,
   setIssueState,
@@ -14,7 +13,6 @@ import {
   createIssue,
   fetchProjects,
   fetchTeams,
-  fetchWorkspaces,
   resolveProjectRef,
   resolveTeamRef,
   getTeamWorkflowStates,
@@ -27,6 +25,7 @@ import {
   updateProjectMilestone,
   deleteProjectMilestone,
   deleteIssue,
+  withHandlerErrorHandling,
 } from './linear.js';
 import { debug } from './logger.js';
 
@@ -73,8 +72,12 @@ async function runGitCommand(args) {
  * @returns {Promise<boolean>}
  */
 async function gitBranchExists(branchName) {
-  const result = await runGitCommand(['rev-parse', '--verify', branchName]);
-  return result.code === 0;
+  try {
+    const result = await runGitCommand(['rev-parse', '--verify', branchName]);
+    return result.code === 0;
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -128,57 +131,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();
-  }
-
-  const resolved = await resolveProjectRef(client, projectRef);
+  return withHandlerErrorHandling(async () => {
+    let projectRef = params.project;
+    if (!projectRef) {
+      projectRef = process.cwd().split('/').pop();
+    }
 
-  let assigneeId = null;
-  if (params.assignee === 'me') {
-    const viewer = await client.viewer;
-    assigneeId = viewer.id;
-  }
+    const resolved = await resolveProjectRef(client, projectRef);
 
-  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

@@ -6,13 +6,185 @@
  */
 
 import { LinearClient } from '@linear/sdk';
-import { debug, warn, error as logError } from './logger.js';
+import { debug, warn, info } 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();
+
+/** @type {Map<string, {total: number, success: number, failed: number, rateLimited: number, windowStart: number, lastSummaryAt: number}>} */
+const requestMetrics = new Map();
+
+/** Track globally if we've detected a rate limit error */
+let globalRateLimited = false;
+let globalRateLimitResetAt = null;
+
+const REQUEST_SUMMARY_INTERVAL = 50;
+const REQUEST_SUMMARY_MIN_MS = 15000;
+
+function getTrackerKey(apiKey) {
+  return apiKey || 'default';
+}
+
+function getRequestMetric(trackerKey) {
+  let metric = requestMetrics.get(trackerKey);
+  if (!metric) {
+    metric = {
+      total: 0,
+      success: 0,
+      failed: 0,
+      rateLimited: 0,
+      windowStart: Date.now(),
+      lastSummaryAt: 0,
+    };
+    requestMetrics.set(trackerKey, metric);
+  }
+  return metric;
+}
+
+function maybeLogRequestSummary(trackerKey) {
+  const metric = requestMetrics.get(trackerKey);
+  const tracker = rateLimitTracker.get(trackerKey);
+  if (!metric || !tracker) return;
+
+  const now = Date.now();
+  const shouldLogByCount = metric.total % REQUEST_SUMMARY_INTERVAL === 0;
+  const shouldLogByTime = now - metric.lastSummaryAt >= REQUEST_SUMMARY_MIN_MS;
+
+  if (!shouldLogByCount && !shouldLogByTime) return;
+
+  metric.lastSummaryAt = now;
+  const used = Math.max(0, 5000 - (tracker.remaining ?? 5000));
+
+  info('[pi-linear-tools] Linear API usage summary', {
+    trackerKey,
+    requestsTotal: metric.total,
+    requestsSuccess: metric.success,
+    requestsFailed: metric.failed,
+    requestsRateLimited: metric.rateLimited,
+    requestsRemaining: tracker.remaining,
+    requestsUsed: used,
+    resetAt: tracker.resetAt,
+    resetTime: tracker.resetAt ? new Date(tracker.resetAt).toLocaleTimeString() : null,
+  });
+}
+
+function extractOperationName(query) {
+  if (!query || typeof query !== 'string') return 'unknown';
+  const compact = query.replace(/\s+/g, ' ').trim();
+  const match = compact.match(/^(query|mutation)\s+([a-zA-Z0-9_]+)/i);
+  return match?.[2] || 'anonymous';
+}
+
+/**
+ * Clear rate limit state if the window has expired
+ * @returns {{isRateLimited: boolean, resetAt: Date|null}}
+ */
+export function checkAndClearRateLimit() {
+  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) };
+}
+
+/**
+ * @deprecated Use checkAndClearRateLimit() instead
+ * @returns {{isRateLimited: boolean, resetAt: Date|null}}
+ */
+export function isGloballyRateLimited() {
+  return checkAndClearRateLimit();
+}
+
+/**
+ * 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(),
+  });
+}
+
 /**
- * Create a Linear SDK client
+ * 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) {
+  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 };
+}
+
+/**
+ * Expose per-client request counters for diagnostics
+ */
+export function getClientRequestMetrics(client) {
+  const key = client?.apiKey || 'default';
+  const metric = requestMetrics.get(key);
+  if (!metric) {
+    return {
+      total: 0,
+      success: 0,
+      failed: 0,
+      rateLimited: 0,
+      windowStart: null,
+    };
+  }
+
+  return {
+    total: metric.total,
+    success: metric.success,
+    failed: metric.failed,
+    rateLimited: metric.rateLimited,
+    windowStart: metric.windowStart,
+  };
+}
+
+/**
+ * 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,31 +202,100 @@ 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(
-        'Auth object must contain either apiKey or accessToken'
-      );
+      throw new Error('Auth object must contain either apiKey or accessToken');
     }
   } else {
-    throw new Error(
-      'Invalid auth parameter: must be a string (API key) or an object with apiKey or accessToken'
-    );
+    throw new Error('Invalid auth parameter: must be a string (API key) or an object with apiKey or accessToken');
+  }
+
+  const client = new LinearClient(clientConfig);
+
+  const trackerKey = getTrackerKey(apiKey);
+  if (!rateLimitTracker.has(trackerKey)) {
+    rateLimitTracker.set(trackerKey, { remaining: 5000, resetAt: Date.now() + 3600000 });
   }
+  getRequestMetric(trackerKey);
+
+  // Wrap internal rawRequest to capture request counts + rate limit metadata
+  const originalRawRequest = client.client.rawRequest.bind(client.client);
+  client.client.rawRequest = async function wrappedRawRequest(query, variables, requestHeaders) {
+    const metric = getRequestMetric(trackerKey);
+    metric.total += 1;
+
+    debug('[pi-linear-tools] Linear request', {
+      trackerKey,
+      requestNumber: metric.total,
+      operation: extractOperationName(query),
+    });
+
+    try {
+      const response = await originalRawRequest(query, variables, requestHeaders);
+      metric.success += 1;
+
+      if (response.headers) {
+        const remaining = response.headers.get('X-RateLimit-Requests-Remaining');
+        const resetAt = response.headers.get('X-RateLimit-Requests-Reset');
+
+        const tracker = rateLimitTracker.get(trackerKey);
+        if (tracker && remaining !== null) {
+          tracker.remaining = parseInt(remaining, 10);
+        }
+        if (tracker && resetAt !== null) {
+          tracker.resetAt = parseInt(resetAt, 10);
+        }
+      }
+
+      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,
+        });
+      }
+
+      maybeLogRequestSummary(trackerKey);
+      return response;
+    } catch (error) {
+      metric.failed += 1;
+
+      const message = String(error?.message || error || 'unknown');
+      const isRateLimited = error?.type === 'Ratelimited' || message.toLowerCase().includes('rate limit');
+
+      if (isRateLimited) {
+        metric.rateLimited += 1;
+        const resetAt = Number(error?.requestsResetAt) || Date.now() + 3600000;
+        const remaining = Number.isFinite(error?.requestsRemaining) ? error.requestsRemaining : 0;
+        rateLimitTracker.set(trackerKey, {
+          remaining,
+          resetAt,
+        });
+        markRateLimited(resetAt);
+      }
+
+      maybeLogRequestSummary(trackerKey);
+      throw error;
+    }
+  };
 
-  return new LinearClient(clientConfig);
+  return client;
 }
 
 /**