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

package/src/auth/oauth.js

@@ -6,6 +6,7 @@
  */
 
 import { debug, warn, error as logError } from '../logger.js';
+import { OAUTH_CLIENT_ID, OAUTH_SCOPES } from './constants.js';
 
 // OAuth configuration
 const OAUTH_CONFIG = {
@@ -15,11 +16,11 @@ const OAUTH_CONFIG = {
   revokeUrl: 'https://api.linear.app/oauth/revoke',
 
   // Client configuration
-  clientId: 'a3e177176c6697611367f1a2405d4a34',
+  clientId: OAUTH_CLIENT_ID,
   redirectUri: 'http://localhost:34711/callback',
 
-  // OAuth scopes - minimal required scopes
-  scopes: ['read', 'issues:create', 'comments:create'],
+  // OAuth scopes
+  scopes: OAUTH_SCOPES,
 
   // Prompt consent to allow workspace reselection
   prompt: 'consent',
@@ -272,10 +273,10 @@ export async function revokeToken(token, tokenTypeHint) {
 }
 
 /**
- * Get OAuth configuration
+ * Get OAuth configuration (internal)
  *
  * @returns {object} OAuth configuration object
  */
-export function getOAuthConfig() {
+function _getOAuthConfig() {
   return { ...OAUTH_CONFIG };
 }

package/src/auth/pkce.js

@@ -6,106 +6,69 @@
  */
 
 import crypto from 'node:crypto';
-import { debug } from '../logger.js';
+import { debug, warn, error as logError } from '../logger.js';
 
 /**
- * Generate a random code verifier for PKCE
- *
- * The code verifier must be:
- * - High-entropy cryptographically random
- * - Between 43 and 128 characters
- * - Containing only alphanumeric characters and '-', '.', '_', '~'
- *
- * @returns {string} Base64URL-encoded code verifier
+ * Generate a random code verifier for PKCE (RFC 7636: 43-128 chars, base64url)
+ * @returns {string} Code verifier
  */
 export function generateCodeVerifier() {
-  // Generate 32 bytes of cryptographically secure random data
-  // Base64URL encoding results in ~43 characters
+  // 32 bytes = ~43 base64url characters
   const verifier = crypto.randomBytes(32).toString('base64url');
-
   debug('Generated code verifier', { length: verifier.length });
-
   return verifier;
 }
 
 /**
- * Generate a code challenge from the verifier
- *
- * Uses SHA-256 hash as specified in PKCE with S256 method.
- *
- * @param {string} verifier - The code verifier generated by generateCodeVerifier()
- * @returns {string} Base64URL-encoded code challenge
+ * Generate a code challenge from verifier (SHA-256, S256 method)
+ * @param {string} verifier - Code verifier
+ * @returns {string} Code challenge
  */
 export function generateCodeChallenge(verifier) {
   const challenge = crypto
     .createHash('sha256')
     .update(verifier)
     .digest('base64url');
-
   debug('Generated code challenge', { challengeLength: challenge.length });
-
   return challenge;
 }
 
 /**
- * Generate a cryptographically random state parameter
- *
- * The state parameter is used for CSRF protection during OAuth flow.
- * Must be unique per authentication session.
- *
- * @returns {string} Hex-encoded random state
+ * Generate a random state parameter for CSRF protection
+ * @returns {string} Hex-encoded state
  */
 export function generateState() {
-  // Generate 16 bytes of random data (32 hex characters)
   const state = crypto.randomBytes(16).toString('hex');
-
   debug('Generated state parameter', { state });
-
   return state;
 }
 
 /**
- * Validate state parameter matches expected value
- *
- * @param {string} receivedState - State received from OAuth callback
- * @param {string} expectedState - State generated at start of flow
- * @returns {boolean} True if states match, false otherwise
+ * Validate OAuth callback state matches expected
+ * @param {string} receivedState - From callback
+ * @param {string} expectedState - Generated at flow start
+ * @returns {boolean} True if match
  */
 export function validateState(receivedState, expectedState) {
   const isValid = receivedState === expectedState;
-
   if (!isValid) {
-    debug('State validation failed', {
-      received: receivedState,
-      expected: expectedState,
-    });
-  } else {
-    debug('State validation successful');
+    debug('State validation failed', { received: receivedState, expected: expectedState });
   }
-
   return isValid;
 }
 
 /**
  * Generate all PKCE parameters for OAuth flow
- *
- * Convenience function that generates all required PKCE parameters.
- *
- * @returns {object} Object containing verifier, challenge, and state
- * @returns {string} returns.verifier - Code verifier
- * @returns {string} returns.challenge - Code challenge
- * @returns {string} returns.state - State parameter
+ * @returns {{verifier: string, challenge: string, state: string}}
  */
 export function generatePkceParams() {
   const verifier = generateCodeVerifier();
   const challenge = generateCodeChallenge(verifier);
   const state = generateState();
-
   debug('Generated PKCE parameters', {
     verifierLength: verifier.length,
     challengeLength: challenge.length,
     stateLength: state.length,
   });
-
   return { verifier, challenge, state };
-}
+}

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,
@@ -29,7 +27,7 @@ import {
   deleteIssue,
   withHandlerErrorHandling,
 } from './linear.js';
-import { debug, warn } from './logger.js';
+import { debug } from './logger.js';
 
 function toTextResult(text, details = {}) {
   return {
@@ -74,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;
+  }
 }
 
 /**

package/src/linear-client.js

@@ -6,7 +6,7 @@
  */
 
 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;
@@ -14,15 +14,75 @@ 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';
+}
+
 /**
- * Check if we know we're rate limited and should skip API calls
+ * Clear rate limit state if the window has expired
  * @returns {{isRateLimited: boolean, resetAt: Date|null}}
  */
-export function isGloballyRateLimited() {
+export function checkAndClearRateLimit() {
   if (!globalRateLimited || !globalRateLimitResetAt) {
     return { isRateLimited: false, resetAt: null };
   }
@@ -37,6 +97,14 @@ export function isGloballyRateLimited() {
   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
@@ -56,7 +124,6 @@ export function markRateLimited(resetAt) {
  * @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 {
@@ -69,6 +136,31 @@ export function getClientRateLimit(client) {
   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
@@ -114,11 +206,9 @@ export function createLinearClient(auth) {
 
   // 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;
@@ -128,61 +218,81 @@ export function createLinearClient(auth) {
       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);
 
-  // Initialize rate limit tracking for this client
-  const trackerKey = apiKey || 'default';
+  const trackerKey = getTrackerKey(apiKey);
   if (!rateLimitTracker.has(trackerKey)) {
     rateLimitTracker.set(trackerKey, { remaining: 5000, resetAt: Date.now() + 3600000 });
   }
+  getRequestMetric(trackerKey);
 
-  // Wrap the rawRequest to capture rate limit headers
-  // rawRequest is on client.client (internal GraphQL client)
+  // 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 response = await originalRawRequest(query, variables, requestHeaders);
+    const metric = getRequestMetric(trackerKey);
+    metric.total += 1;
+
+    debug('[pi-linear-tools] Linear request', {
+      trackerKey,
+      requestNumber: metric.total,
+      operation: extractOperationName(query),
+    });
 
-    // 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');
+    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');
 
-      if (remaining !== null) {
         const tracker = rateLimitTracker.get(trackerKey);
-        if (tracker) {
+        if (tracker && remaining !== null) {
           tracker.remaining = parseInt(remaining, 10);
         }
-      }
-      if (resetAt !== null) {
-        const tracker = rateLimitTracker.get(trackerKey);
-        if (tracker) {
+        if (tracker && resetAt !== null) {
           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,
-      });
-    }
+      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;
+      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 client;

package/src/linear.js

@@ -139,10 +139,10 @@ const rateLimitState = {
 };
 
 /**
- * Update rate limit state from response headers
+ * Update rate limit state from response headers (internal)
  * @param {Response} response - Fetch response object
  */
-export function updateRateLimitState(response) {
+function updateRateLimitState(response) {
   if (!response) return;
 
   const headers = response.headers;
@@ -224,15 +224,14 @@ function isLinearError(error) {
 /**
  * Format a Linear API error into a user-friendly message
  * @param {Error} error - The original error
- * @returns {Error} Formatted error with user-friendly message
+ * @returns {Error|unknown} Formatted error with user-friendly message, or original if unhandled
  */
 function formatLinearError(error) {
   const message = String(error?.message || error || 'Unknown error');
   const errorType = error?.type || 'Unknown';
 
-  // Rate limit error
+  // Rate limit: provide reset time and reduce-frequency hint
   if (errorType === 'Ratelimited' || message.toLowerCase().includes('rate limit')) {
-    const retryAfter = error?.retryAfter;
     const resetAt = error?.requestsResetAt
       ? new Date(error.requestsResetAt).toLocaleTimeString()
       : '1 hour';
@@ -244,7 +243,7 @@ function formatLinearError(error) {
     );
   }
 
-  // Authentication/Forbidden errors
+  // Auth/permission failures: prompt to check credentials
   if (errorType === 'Forbidden' || errorType === 'AuthenticationError' ||
     message.toLowerCase().includes('forbidden') || message.toLowerCase().includes('unauthorized')) {
     return new Error(
@@ -273,7 +272,8 @@ function formatLinearError(error) {
     );
   }
 
-  return error;
+  // Unknown error - wrap if not already an Error
+  return error instanceof Error ? error : new Error(String(error));
 }
 
 /**
@@ -889,14 +889,12 @@ export async function fetchIssueDetails(client, issueRef, options = {}) {
       };
     }
 
-    // Transform children
     const children = (childrenResult.nodes || []).map(c => ({
       identifier: c.identifier,
       title: c.title,
       state: c.state ? { name: c.state.name, color: c.state.color } : null,
     }));
 
-    // Transform comments
     const comments = (commentsResult.nodes || []).map(c => ({
       id: c.id,
       body: c.body,
@@ -907,7 +905,6 @@ export async function fetchIssueDetails(client, issueRef, options = {}) {
       parent: c.parent ? { id: c.parent.id } : null,
     }));
 
-    // Transform attachments
     const attachments = (attachmentsResult.nodes || []).map(a => ({
       id: a.id,
       title: a.title,
@@ -917,7 +914,6 @@ export async function fetchIssueDetails(client, issueRef, options = {}) {
       createdAt: a.createdAt,
     }));
 
-    // Transform labels
     const labels = (labelsResult.nodes || []).map(l => ({
       id: l.id,
       name: l.name,
@@ -1424,7 +1420,6 @@ export async function fetchMilestoneDetails(client, milestoneId) {
       milestone.issues?.()?.catch?.(() => ({ nodes: [] })) ?? milestone.issues?.() ?? { nodes: [] },
     ]);
 
-    // Transform issues
     const issues = await Promise.all(
       (issuesResult.nodes || []).map(async (issue) => {
         const [state, assignee] = await Promise.all([