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

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## v0.4.0 (2026-03-23)
+
+Comprehensive error handling and file-first logging release.
+
+### New Features
+- **File-first logging**: Structured JSON logs written to `~/.config/pi-linear-tools/` instead of stdout (TUI-safe)
+- **Request metrics tracking**: Monitor total/success/failed/rate-limited requests per client
+- **Periodic usage summaries**: Logged every 50 requests or 15 seconds
+
+### Bug Fixes
+- All tool `execute()` functions now wrapped with comprehensive try/catch
+- Never let raw SDK errors propagate to users
+- Extension initialization protected with safety wrapper
+
+### Improvements
+- Clear user-facing error messages for:
+  - Rate limit errors (with reset times)
+  - Authentication/authorization failures
+  - Network errors
+  - Server errors (5xx)
+- Graceful handling when `pi.registerTool` is unavailable
+- Better error context for debugging
+
 ## v0.3.0 (2026-03-22)
 
 Rate limit optimization and crash prevention release.

package/extensions/pi-linear-tools.js

@@ -1,75 +1,12 @@
 import { loadSettings, saveSettings } from '../src/settings.js';
-import { createLinearClient, isGloballyRateLimited, markRateLimited } from '../src/linear-client.js';
+import { createLinearClient, checkAndClearRateLimit, markRateLimited } from '../src/linear-client.js';
 import { setQuietMode } from '../src/logger.js';
 import {
   resolveProjectRef,
   fetchTeams,
   fetchWorkspaces,
 } from '../src/linear.js';
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-function isPiCodingAgentRoot(dir) {
-  const pkgPath = path.join(dir, 'package.json');
-  if (!fs.existsSync(pkgPath)) return false;
-  try {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    return pkg?.name === '@mariozechner/pi-coding-agent';
-  } catch {
-    return false;
-  }
-}
-
-function findPiCodingAgentRoot() {
-  const entry = process.argv?.[1];
-  if (!entry) return null;
-
-  // Method 1: walk up from argv1 (works when argv1 is .../pi-coding-agent/dist/cli.js)
-  {
-    let dir = path.dirname(entry);
-    for (let i = 0; i < 20; i += 1) {
-      if (isPiCodingAgentRoot(dir)) {
-        return dir;
-      }
-      const parent = path.dirname(dir);
-      if (parent === dir) break;
-      dir = parent;
-    }
-  }
-
-  // Method 2: npm global layout guess (works when argv1 is .../<prefix>/bin/pi)
-  // <prefix>/bin/pi  ->  <prefix>/lib/node_modules/@mariozechner/pi-coding-agent
-  {
-    const binDir = path.dirname(entry);
-    const prefix = path.resolve(binDir, '..');
-    const candidate = path.join(prefix, 'lib', 'node_modules', '@mariozechner', 'pi-coding-agent');
-    if (isPiCodingAgentRoot(candidate)) {
-      return candidate;
-    }
-  }
-
-  // Method 3: common global node_modules locations
-  for (const candidate of [
-    '/usr/local/lib/node_modules/@mariozechner/pi-coding-agent',
-    '/usr/lib/node_modules/@mariozechner/pi-coding-agent',
-  ]) {
-    if (isPiCodingAgentRoot(candidate)) {
-      return candidate;
-    }
-  }
-
-  return null;
-}
-
-async function importFromPiRoot(relativePathFromPiRoot) {
-  const piRoot = findPiCodingAgentRoot();
-
-  if (!piRoot) throw new Error('Unable to locate @mariozechner/pi-coding-agent installation');
-
-  const absPath = path.join(piRoot, relativePathFromPiRoot);
-  return import(pathToFileURL(absPath).href);
-}
+import { isPiCodingAgentRoot, findPiCodingAgentRoot, importFromPiRoot, parseArgs, readFlag } from '../src/shared.js';
 
 async function importPiCodingAgent() {
   try {
@@ -125,23 +62,7 @@ import {
   executeMilestoneDelete,
 } from '../src/handlers.js';
 import { authenticate, getAccessToken, logout } from '../src/auth/index.js';
-
-function parseArgs(argsString) {
-  if (!argsString || !argsString.trim()) return [];
-  const tokens = argsString.match(/"[^"]*"|'[^']*'|\S+/g) || [];
-  return tokens.map((t) => {
-    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
-      return t.slice(1, -1);
-    }
-    return t;
-  });
-}
-
-function readFlag(args, flag) {
-  const idx = args.indexOf(flag);
-  if (idx >= 0 && idx + 1 < args.length) return args[idx + 1];
-  return undefined;
-}
+import { withMilestoneScopeHint } from '../src/error-hints.js';
 
 let cachedApiKey = null;
 
@@ -185,19 +106,6 @@ async function createAuthenticatedClient() {
   return createLinearClient(await getLinearAuth());
 }
 
-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;
-}
-
 async function resolveDefaultTeam(projectId) {
   const settings = await loadSettings();
 
@@ -632,7 +540,7 @@ async function registerLinearTools(pi) {
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
       // Pre-check: skip API calls if we know we're rate limited
-      const { isRateLimited, resetAt } = isGloballyRateLimited();
+      const { isRateLimited, resetAt } = checkAndClearRateLimit();
       if (isRateLimited) {
         throw new Error(
           `Linear API rate limit exceeded (cached).\n\n` +

package/index.js

@@ -1,75 +1,12 @@
 import { loadSettings, saveSettings } from './src/settings.js';
-import { createLinearClient } from './src/linear-client.js';
+import { createLinearClient, checkAndClearRateLimit, markRateLimited } from './src/linear-client.js';
 import { setQuietMode } from './src/logger.js';
 import {
   resolveProjectRef,
   fetchTeams,
   fetchWorkspaces,
 } from './src/linear.js';
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-function isPiCodingAgentRoot(dir) {
-  const pkgPath = path.join(dir, 'package.json');
-  if (!fs.existsSync(pkgPath)) return false;
-  try {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    return pkg?.name === '@mariozechner/pi-coding-agent';
-  } catch {
-    return false;
-  }
-}
-
-function findPiCodingAgentRoot() {
-  const entry = process.argv?.[1];
-  if (!entry) return null;
-
-  // Method 1: walk up from argv1 (works when argv1 is .../pi-coding-agent/dist/cli.js)
-  {
-    let dir = path.dirname(entry);
-    for (let i = 0; i < 20; i += 1) {
-      if (isPiCodingAgentRoot(dir)) {
-        return dir;
-      }
-      const parent = path.dirname(dir);
-      if (parent === dir) break;
-      dir = parent;
-    }
-  }
-
-  // Method 2: npm global layout guess (works when argv1 is .../<prefix>/bin/pi)
-  // <prefix>/bin/pi  ->  <prefix>/lib/node_modules/@mariozechner/pi-coding-agent
-  {
-    const binDir = path.dirname(entry);
-    const prefix = path.resolve(binDir, '..');
-    const candidate = path.join(prefix, 'lib', 'node_modules', '@mariozechner', 'pi-coding-agent');
-    if (isPiCodingAgentRoot(candidate)) {
-      return candidate;
-    }
-  }
-
-  // Method 3: common global node_modules locations
-  for (const candidate of [
-    '/usr/local/lib/node_modules/@mariozechner/pi-coding-agent',
-    '/usr/lib/node_modules/@mariozechner/pi-coding-agent',
-  ]) {
-    if (isPiCodingAgentRoot(candidate)) {
-      return candidate;
-    }
-  }
-
-  return null;
-}
-
-async function importFromPiRoot(relativePathFromPiRoot) {
-  const piRoot = findPiCodingAgentRoot();
-
-  if (!piRoot) throw new Error('Unable to locate @mariozechner/pi-coding-agent installation');
-
-  const absPath = path.join(piRoot, relativePathFromPiRoot);
-  return import(pathToFileURL(absPath).href);
-}
+import { isPiCodingAgentRoot, findPiCodingAgentRoot, importFromPiRoot, parseArgs, readFlag } from './src/shared.js';
 
 async function importPiCodingAgent() {
   try {
@@ -125,23 +62,7 @@ import {
   executeMilestoneDelete,
 } from './src/handlers.js';
 import { authenticate, getAccessToken, logout } from './src/auth/index.js';
-
-function parseArgs(argsString) {
-  if (!argsString || !argsString.trim()) return [];
-  const tokens = argsString.match(/"[^"]*"|'[^']*'|\S+/g) || [];
-  return tokens.map((t) => {
-    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
-      return t.slice(1, -1);
-    }
-    return t;
-  });
-}
-
-function readFlag(args, flag) {
-  const idx = args.indexOf(flag);
-  if (idx >= 0 && idx + 1 < args.length) return args[idx + 1];
-  return undefined;
-}
+import { withMilestoneScopeHint } from './src/error-hints.js';
 
 let cachedApiKey = null;
 
@@ -185,19 +106,6 @@ async function createAuthenticatedClient() {
   return createLinearClient(await getLinearAuth());
 }
 
-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;
-}
-
 async function resolveDefaultTeam(projectId) {
   const settings = await loadSettings();
 
@@ -502,7 +410,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 +539,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 } = checkAndClearRateLimit();
+      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 +645,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 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.`);
+        }
 
-      switch (params.action) {
-        case 'list':
-          return executeProjectList(client);
-        default:
-          throw new Error(`Unknown action: ${params.action}`);
+        if (errorMessage.includes('Linear API error:')) {
+          throw error;
+        }
+
+        throw new Error(`Linear project operation failed: ${errorMessage}`);
       }
     },
   });
@@ -702,13 +693,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.`);
+        }
 
-      switch (params.action) {
-        case 'list':
-          return executeTeamList(client);
-        default:
-          throw new Error(`Unknown action: ${params.action}`);
+        if (errorMessage.includes('Linear API error:')) {
+          throw error;
+        }
+
+        throw new Error(`Linear team operation failed: ${errorMessage}`);
       }
     },
   });
@@ -752,9 +762,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 +780,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 +805,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 +944,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.3.0",
+  "version": "0.4.0",
   "description": "Pi extension with Linear SDK tools and configuration commands",
   "type": "module",
   "engines": {
@@ -46,6 +46,6 @@
   "license": "MIT",
   "dependencies": {
     "@linear/sdk": "^75.0.0",
-    "keytar": "^7.9.0"
+    "@github/keytar": "^7.10.6"
   }
 }

package/src/auth/callback-server.js

@@ -7,7 +7,7 @@
 
 import http from 'node:http';
 import { URL } from 'node:url';
-import { debug, warn, error as logError } from '../logger.js';
+import { debug, error as logError } from '../logger.js';
 
 // Default callback server configuration
 const SERVER_CONFIG = {

package/src/auth/constants.js

@@ -0,0 +1,9 @@
+/**
+ * OAuth constants for pi-linear-tools
+ */
+
+// Linear OAuth application client ID
+export const OAUTH_CLIENT_ID = 'a3e177176c6697611367f1a2405d4a34';
+
+// OAuth scopes - minimal required scopes
+export const OAUTH_SCOPES = ['read', 'issues:create', 'comments:create'];

package/src/auth/index.js

@@ -6,10 +6,9 @@
  */
 
 import { generatePkceParams } from './pkce.js';
-import { buildAuthorizationUrl, exchangeCodeForToken } from './oauth.js';
+import { buildAuthorizationUrl, exchangeCodeForToken, refreshAccessToken, revokeToken } from './oauth.js';
 import { waitForCallback } from './callback-server.js';
-import { storeTokens, getTokens, clearTokens, hasValidTokens } from './token-store.js';
-import { getValidAccessToken } from './token-refresh.js';
+import { storeTokens, getTokens, clearTokens } from './token-store.js';
 import { debug, info, warn, error as logError } from '../logger.js';
 
 function parseManualCallbackInput(rawInput) {
@@ -184,10 +183,41 @@ export async function authenticate({
 /**
  * Get a valid access token, refreshing if necessary
  *
- * @returns {Promise<string|null>} Valid access token or null if not authenticated
+ * @returns {Promise<string|null>} Valid access token, or null if no auth configured or refresh failed
  */
 export async function getAccessToken() {
-  return getValidAccessToken(getTokens);
+  const tokens = await getTokens();
+
+  if (!tokens) {
+    return null;
+  }
+
+  const now = Date.now();
+  const bufferSeconds = 60;
+  const bufferMs = bufferSeconds * 1000;
+
+  // Check if token is still valid (with buffer)
+  if (now < tokens.expiresAt - bufferMs) {
+    return tokens.accessToken;
+  }
+
+  // Token needs refresh
+  try {
+    const tokenResponse = await refreshAccessToken(tokens.refreshToken);
+    const expiresAt = Date.now() + tokenResponse.expires_in * 1000;
+    const newTokens = {
+      accessToken: tokenResponse.access_token,
+      refreshToken: tokenResponse.refresh_token,
+      expiresAt: expiresAt,
+      scope: tokenResponse.scope ? tokenResponse.scope.split(' ') : [],
+      tokenType: tokenResponse.token_type || 'Bearer',
+    };
+    await storeTokens(newTokens);
+    return newTokens.accessToken;
+  } catch (error) {
+    debug('Failed to get valid access token', { error: error.message });
+    return null;
+  }
 }
 
 /**
@@ -196,7 +226,11 @@ export async function getAccessToken() {
  * @returns {Promise<boolean>} True if authenticated with valid tokens
  */
 export async function isAuthenticated() {
-  return hasValidTokens();
+  const tokens = await getTokens();
+  if (!tokens) {
+    return false;
+  }
+  return Date.now() < tokens.expiresAt;
 }
 
 /**
@@ -223,12 +257,21 @@ export async function getAuthStatus() {
 }
 
 /**
- * Logout (clear stored tokens)
+ * Logout (clear stored tokens and revoke OAuth tokens)
  *
  * @returns {Promise<void>}
  */
 export async function logout() {
   info('Logging out...');
+  const tokens = await getTokens();
+  if (tokens?.accessToken) {
+    try {
+      await revokeToken(tokens.accessToken);
+      debug('OAuth token revoked');
+    } catch {
+      // Ignore revocation errors - we still want to clear local tokens
+    }
+  }
   await clearTokens();
   info('Logged out successfully');
 }