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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pi extension with Linear SDK tools and configuration commands",
   "type": "module",
   "engines": {
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node tests/test-package-manifest.js && node tests/test-extension-registration.js && node tests/test-settings.js && node tests/test-assignee-update.js && node tests/test-full-assignee-flow.js",
+    "test": "node tests/test-package-manifest.js && node tests/test-extension-registration.js && node tests/test-settings.js && node tests/test-assignee-update.js && node tests/test-full-assignee-flow.js && node tests/test-branch-param.js",
     "dev:sync-local-extension": "node scripts/dev-sync-local-extension.mjs",
     "release:check": "npm test && npm pack --dry-run"
   },
@@ -40,7 +40,7 @@
   ],
   "pi": {
     "extensions": [
-      "./extensions"
+      "./index.js"
     ]
   },
   "license": "MIT",

package/src/auth/token-store.js

@@ -73,7 +73,7 @@ async function writeTokensToFile(tokenData) {
   await mkdir(parentDir, { recursive: true, mode: 0o700 });
   await writeFile(tokenFilePath, tokenData, { encoding: 'utf-8', mode: 0o600 });
 
-  warn('Stored OAuth tokens in fallback file storage because keychain is unavailable', {
+  debug('Stored OAuth tokens in fallback file storage because keychain is unavailable', {
     path: tokenFilePath,
   });
 }
@@ -94,7 +94,7 @@ async function isKeytarAvailable() {
     debug('keytar module loaded successfully');
     return true;
   } catch (error) {
-    warn('keytar module not available, using fallback storage', { error: error.message });
+    debug('keytar module not available, using fallback storage', { error: error.message });
     keytarModule = false;
     return false;
   }
@@ -153,7 +153,7 @@ export async function storeTokens(tokens) {
       // Clean up fallback file if keychain works again
       await unlink(getTokenFilePath()).catch(() => {});
     } catch (error) {
-      warn('Failed to store tokens in keychain, falling back to file storage', {
+      debug('Failed to store tokens in keychain, falling back to file storage', {
         error: error.message,
       });
       await writeTokensToFile(tokenData);
@@ -235,7 +235,7 @@ export async function getTokens() {
 
       debug('No tokens found in keychain');
     } catch (error) {
-      warn('Failed to retrieve tokens from keychain, trying fallback storage', {
+      debug('Failed to retrieve tokens from keychain, trying fallback storage', {
         error: error.message,
       });
     }
@@ -277,7 +277,7 @@ export async function clearTokens() {
       const message = String(error?.message || 'Unknown error');
       // Keychain providers (e.g. DBus Secret Service) may be unavailable at runtime.
       // Clearing is best-effort and we still clear fallback file/in-memory tokens below.
-      warn('Skipping keychain token clear; keychain backend unavailable', {
+      debug('Skipping keychain token clear; keychain backend unavailable', {
         error: message,
       });
       if (/org\.freedesktop\.secrets/i.test(message)) {

package/src/cli.js

@@ -143,15 +143,17 @@ Usage:
   pi-linear-tools <command> [options]
 
 Commands:
+  issue <action> [options]      Manage issues
+  project <action> [options]    Manage projects
+  team <action> [options]       Manage teams
+  milestone <action> [options]  Manage milestones
+
+Other commands:
   help                          Show this help message
   auth <action>                 Manage authentication (OAuth 2.0)
   config                        Show current configuration
   config --api-key <key>        Set Linear API key (legacy)
   config --default-team <key>   Set default team
-  issue <action> [options]      Manage issues
-  project <action> [options]    Manage projects
-  team <action> [options]       Manage teams
-  milestone <action> [options]  Manage milestones
 
 Auth Actions:
   login    Authenticate with Linear via OAuth 2.0
@@ -165,7 +167,7 @@ Issue Actions:
   update <issue> [--title X] [--description X] [--state X] [--priority 0-4]
          [--assignee me|ID] [--milestone X] [--sub-issue-of X]
   comment <issue> --body X
-  start <issue> [--branch X] [--from-ref X] [--on-branch-exists switch|suffix]
+  start <issue> [--from-ref X] [--on-branch-exists switch|suffix]
   delete <issue>
 
 Project Actions:
@@ -201,10 +203,10 @@ Examples:
   pi-linear-tools config --api-key lin_xxx
 
 Authentication:
-  OAuth 2.0 is the recommended authentication method.
-  Run 'pi-linear-tools auth login' to authenticate.
-  For CI/headless environments, set environment variables:
-    LINEAR_ACCESS_TOKEN, LINEAR_REFRESH_TOKEN, LINEAR_EXPIRES_AT
+  API key is the recommended authentication method (supports milestones).
+  Run 'pi-linear-tools config --api-key <key>' to authenticate.
+  For CI/headless environments, set the LINEAR_API_KEY environment variable.
+  OAuth 2.0 is also available via 'pi-linear-tools auth login'.
 `);
 }
 
@@ -258,7 +260,6 @@ Comment Options:
 
 Start Options:
   <issue>          Issue key or ID
-  --branch X       Custom branch name (default: issue's branch name)
   --from-ref X     Git ref to branch from (default: HEAD)
   --on-branch-exists X  "switch" or "suffix" (default: switch)
 
@@ -642,7 +643,6 @@ async function handleIssueStart(args) {
 
   const params = {
     issue: positional[0],
-    branch: readFlag(args, '--branch'),
     fromRef: readFlag(args, '--from-ref'),
     onBranchExists: readFlag(args, '--on-branch-exists'),
   };

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');
 }
 
 /**
@@ -447,28 +450,31 @@ export async function executeIssueStart(client, params, options = {}) {
   const issue = ensureNonEmpty(params.issue, 'issue');
   const prepared = await prepareIssueStart(client, issue);
 
-  const desiredBranch = params.branch || prepared.branchName;
-  if (!desiredBranch) {
+  // Always use Linear's suggested branchName - it cannot be changed via API
+  // and using a custom branch would break Linear's branch-to-issue linking
+  const branchName = prepared.branchName;
+  if (!branchName) {
     throw new Error(
-      `No branch name resolved for issue ${prepared.issue.identifier}. Provide the 'branch' parameter explicitly.`
+      `No branch name available for issue ${prepared.issue.identifier}. The issue may not have a team assigned.`
     );
   }
 
   let gitResult;
   if (gitExecutor) {
     // Use provided git executor (e.g., pi.exec)
-    gitResult = await gitExecutor(desiredBranch, params.fromRef || 'HEAD', params.onBranchExists || 'switch');
+    gitResult = await gitExecutor(branchName, params.fromRef || 'HEAD', params.onBranchExists || 'switch');
   } else {
     // Use built-in child_process git operations
-    gitResult = await startGitBranch(desiredBranch, params.fromRef || 'HEAD', params.onBranchExists || 'switch');
+    gitResult = await startGitBranch(branchName, params.fromRef || 'HEAD', params.onBranchExists || 'switch');
   }
 
   const updatedIssue = await setIssueState(client, prepared.issue.id, prepared.startedState.id);
 
+  const identifier = updatedIssue.identifier || prepared.issue.identifier;
   const compactTitle = String(updatedIssue.title || prepared.issue?.title || '').trim().toLowerCase();
   const summary = compactTitle
-    ? `Started issue ${updatedIssue.identifier} (${compactTitle})`
-    : `Started issue ${updatedIssue.identifier}`;
+    ? `Started issue ${identifier} (${compactTitle})`
+    : `Started issue ${identifier}`;
 
   return toTextResult(summary, {
     issueId: updatedIssue.id,
@@ -731,11 +737,11 @@ export async function executeMilestoneCreate(client, params) {
 export async function executeMilestoneUpdate(client, params) {
   const milestoneId = ensureNonEmpty(params.milestone, 'milestone');
 
+  // Note: status is not included as it's a computed/read-only field in Linear's API
   const result = await updateProjectMilestone(client, milestoneId, {
     name: params.name,
     description: params.description,
     targetDate: params.targetDate,
-    status: params.status,
   });
 
   const friendlyChanges = result.changed;

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;
 }
 
 /**