@fink-andreas/pi-linear-tools 0.4.2 → 0.5.0

package/extensions/pi-linear-tools.js

@@ -48,12 +48,25 @@ try {
 import {
   executeIssueList,
   executeIssueView,
+  executeIssueActivity,
   executeIssueCreate,
   executeIssueUpdate,
   executeIssueComment,
   executeIssueStart,
   executeIssueDelete,
   executeProjectList,
+  executeProjectView,
+  executeProjectCreate,
+  executeProjectUpdate,
+  executeProjectDelete,
+  executeProjectArchive,
+  executeProjectUnarchive,
+  executeProjectUpdateList,
+  executeProjectUpdateView,
+  executeProjectUpdateCreate,
+  executeProjectUpdateUpdate,
+  executeProjectUpdateArchive,
+  executeProjectUpdateUnarchive,
   executeTeamList,
   executeMilestoneList,
   executeMilestoneView,
@@ -439,6 +452,51 @@ async function shouldExposeMilestoneTool() {
 /**
  * Render tool result as markdown
  */
+function toToolTextResult(text, details = {}) {
+  return {
+    content: [{ type: 'text', text }],
+    details,
+  };
+}
+
+function buildRateLimitToolResult(error, options = {}) {
+  const { cached = false } = options;
+  const resetTimestamp = error?.requestsResetAt || Date.now() + 3600000;
+  const resetTime = new Date(resetTimestamp).toLocaleTimeString();
+
+  markRateLimited(resetTimestamp);
+
+  return toToolTextResult(
+    cached
+      ? `Linear API rate limit exceeded (cached).\n\nThe rate limit resets at: ${resetTime}\n\nPlease wait before making more requests.`
+      : `Linear API rate limit exceeded.\n\nThe rate limit resets at: ${resetTime}\n\nPlease wait before making more requests, or reduce the frequency of API calls.`,
+    {
+      error: true,
+      errorType: 'Ratelimited',
+      rateLimited: true,
+      cached,
+      requestsResetAt: resetTimestamp,
+      resetTime,
+    }
+  );
+}
+
+function handleToolExecutionError(error, operationLabel, options = {}) {
+  const transformedError = options.transformError ? options.transformError(error) : error;
+  const errorType = error?.type || transformedError?.type || '';
+  const errorMessage = String(transformedError?.message || transformedError || 'Unknown error');
+
+  if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
+    return buildRateLimitToolResult(error);
+  }
+
+  if (errorMessage.includes('Linear API error:')) {
+    throw transformedError;
+  }
+
+  throw new Error(`${operationLabel}: ${errorMessage}`);
+}
+
 function renderMarkdownResult(result, _options, _theme) {
   const text = result.content?.[0]?.text || '';
 
@@ -478,18 +536,19 @@ async function registerLinearTools(pi) {
   pi.registerTool({
     name: 'linear_issue',
     label: 'Linear Issue',
-    description: 'Interact with Linear issues. Actions: list, view, create, update, comment, start, delete',
+    description: 'Interact with Linear issues.',
+    promptSnippet: 'Interact with Linear issues (list, view, activity, create, update, comment, start, delete)',
     parameters: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'view', 'create', 'update', 'comment', 'start', 'delete'],
+          enum: ['list', 'view', 'activity', 'create', 'update', 'comment', 'start', 'delete'],
           description: 'Action to perform on issue(s)',
         },
         issue: {
           type: 'string',
-          description: 'Issue key (ABC-123) or Linear issue ID (for view, update, comment, start, delete)',
+          description: 'Issue key (ABC-123) or Linear issue ID (for view, activity, update, comment, start, delete)',
         },
         project: {
           type: 'string',
@@ -509,8 +568,8 @@ async function registerLinearTools(pi) {
           description: 'Optional explicit assignee ID alias for update/create debugging/compatibility.',
         },
         limit: {
-          type: 'number',
-          description: 'Maximum number of issues to list (default: 50)',
+          type: 'integer',
+          description: 'Maximum number of issues or activity entries to list',
         },
         includeComments: {
           type: 'boolean',
@@ -525,9 +584,13 @@ async function registerLinearTools(pi) {
           description: 'Issue description in markdown (for create, update)',
         },
         priority: {
-          type: 'number',
+          type: 'integer',
           description: 'Priority 0..4 (for create, update)',
         },
+        includeArchived: {
+          type: 'boolean',
+          description: 'Include archived resources when listing activity or project updates',
+        },
         state: {
           type: 'string',
           description: 'Target state name or ID (for create, update)',
@@ -568,6 +631,10 @@ async function registerLinearTools(pi) {
           type: 'string',
           description: 'For update: mark this issue as duplicate of the given issue key/ID.',
         },
+        estimate: {
+          type: 'integer',
+          description: 'Estimate/story points for the issue (non-negative integer, for create/update)',
+        },
         team: {
           type: 'string',
           description: 'Team key (e.g. ENG) or name (optional if default team configured)',
@@ -599,17 +666,13 @@ 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 } = 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 {
+        // Pre-check: skip API calls if we know we're rate limited
+        const { isRateLimited, resetAt } = checkAndClearRateLimit();
+        if (isRateLimited) {
+          return buildRateLimitToolResult({ requestsResetAt: resetAt.getTime(), type: 'Ratelimited' }, { cached: true });
+        }
+
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_issue', params.action, async () => {
@@ -618,6 +681,8 @@ async function registerLinearTools(pi) {
               return await executeIssueList(client, params);
             case 'view':
               return await executeIssueView(client, params);
+            case 'activity':
+              return await executeIssueActivity(client, params);
             case 'create':
               return await executeIssueCreate(client, params, { resolveDefaultTeam });
             case 'update':
@@ -641,18 +706,6 @@ async function registerLinearTools(pi) {
         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')) {
@@ -678,13 +731,7 @@ async function registerLinearTools(pi) {
           );
         }
 
-        // 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}`);
+        return handleToolExecutionError(error, 'Linear issue operation failed');
       }
     },
   });
@@ -692,15 +739,59 @@ async function registerLinearTools(pi) {
   pi.registerTool({
     name: 'linear_project',
     label: 'Linear Project',
-    description: 'Interact with Linear projects. Actions: list',
+    description: 'Interact with Linear projects.',
+    promptSnippet: 'Interact with Linear projects (list, view, create, update, delete, archive, unarchive)',
     parameters: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['list'],
+          enum: ['list', 'view', 'create', 'update', 'delete', 'archive', 'unarchive'],
           description: 'Action to perform on project(s)',
         },
+        project: {
+          type: 'string',
+          description: 'Project name or ID (for view, update, delete)',
+        },
+        name: {
+          type: 'string',
+          description: 'Project name (required for create, optional for update)',
+        },
+        teams: {
+          type: 'string',
+          description: 'Comma-separated team keys or IDs (required for create, optional for update)',
+        },
+        description: {
+          type: 'string',
+          description: 'Project description in markdown',
+        },
+        lead: {
+          type: 'string',
+          description: 'Project lead user ID, "me", or "none" when updating',
+        },
+        priority: {
+          type: 'integer',
+          description: 'Priority 0-4',
+          minimum: 0,
+          maximum: 4,
+          multipleOf: 1,
+        },
+        color: {
+          type: 'string',
+          description: 'Project color (hex)',
+        },
+        icon: {
+          type: 'string',
+          description: 'Project icon',
+        },
+        startDate: {
+          type: 'string',
+          description: 'Planned start date (YYYY-MM-DD)',
+        },
+        targetDate: {
+          type: 'string',
+          description: 'Planned target date (YYYY-MM-DD)',
+        },
       },
       required: ['action'],
       additionalProperties: false,
@@ -714,27 +805,101 @@ async function registerLinearTools(pi) {
           switch (params.action) {
             case 'list':
               return await executeProjectList(client);
+            case 'view':
+              return await executeProjectView(client, params);
+            case 'create':
+              return await executeProjectCreate(client, params);
+            case 'update':
+              return await executeProjectUpdate(client, params);
+            case 'delete':
+              return await executeProjectDelete(client, params);
+            case 'archive':
+              return await executeProjectArchive(client, params);
+            case 'unarchive':
+              return await executeProjectUnarchive(client, params);
             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.`);
-        }
+        return handleToolExecutionError(error, 'Linear project operation failed');
+      }
+    },
+  });
 
-        if (errorMessage.includes('Linear API error:')) {
-          throw error;
-        }
+  pi.registerTool({
+    name: 'linear_project_update',
+    label: 'Linear Project Update',
+    description: 'Interact with Linear project updates.',
+    promptSnippet: 'Interact with Linear project updates (list, view, create, update, archive, unarchive)',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'view', 'create', 'update', 'archive', 'unarchive'],
+          description: 'Action to perform on project update(s)',
+        },
+        project: {
+          type: 'string',
+          description: 'Project name or ID (for list, create)',
+        },
+        projectUpdate: {
+          type: 'string',
+          description: 'Project update ID (for view, update, archive, unarchive)',
+        },
+        body: {
+          type: 'string',
+          description: 'Project update body in markdown',
+        },
+        health: {
+          type: 'string',
+          description: 'Project update health: onTrack, atRisk, or offTrack',
+          enum: ['onTrack', 'atRisk', 'offTrack'],
+        },
+        isDiffHidden: {
+          type: 'boolean',
+          description: 'Whether to hide the diff on the update',
+        },
+        limit: {
+          type: 'integer',
+          description: 'Max updates to list',
+          minimum: 1,
+          multipleOf: 1,
+        },
+        includeArchived: {
+          type: 'boolean',
+          description: 'Whether archived updates should be included when listing',
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    renderResult: renderMarkdownResult,
+    async execute(_toolCallId, params) {
+      try {
+        const client = await createAuthenticatedClient();
 
-        throw new Error(`Linear project operation failed: ${errorMessage}`);
+        return await withRequestUsageLogging(client, 'linear_project_update', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeProjectUpdateList(client, params);
+            case 'view':
+              return await executeProjectUpdateView(client, params);
+            case 'create':
+              return await executeProjectUpdateCreate(client, params);
+            case 'update':
+              return await executeProjectUpdateUpdate(client, params);
+            case 'archive':
+              return await executeProjectUpdateArchive(client, params);
+            case 'unarchive':
+              return await executeProjectUpdateUnarchive(client, params);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
+      } catch (error) {
+        return handleToolExecutionError(error, 'Linear project update operation failed');
       }
     },
   });
@@ -742,7 +907,8 @@ async function registerLinearTools(pi) {
   pi.registerTool({
     name: 'linear_team',
     label: 'Linear Team',
-    description: 'Interact with Linear teams. Actions: list',
+    description: 'Interact with Linear teams.',
+    promptSnippet: 'Interact with Linear teams (list)',
     parameters: {
       type: 'object',
       properties: {
@@ -769,22 +935,7 @@ async function registerLinearTools(pi) {
           }
         });
       } 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}`);
+        return handleToolExecutionError(error, 'Linear team operation failed');
       }
     },
   });
@@ -793,7 +944,8 @@ async function registerLinearTools(pi) {
     pi.registerTool({
       name: 'linear_milestone',
       label: 'Linear Milestone',
-      description: 'Interact with Linear project milestones. Actions: list, view, create, update, delete',
+      description: 'Interact with Linear project milestones.',
+      promptSnippet: 'Interact with Linear milestones (list, view, create, update, delete)',
       parameters: {
         type: 'object',
         properties: {
@@ -848,24 +1000,9 @@ async function registerLinearTools(pi) {
             }
           });
         } catch (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}`);
+          return handleToolExecutionError(error, 'Linear milestone operation failed', {
+            transformError: withMilestoneScopeHint,
+          });
         }
       },
     });
@@ -983,8 +1120,9 @@ export default async function piLinearToolsExtension(pi) {
       const showMilestoneTool = await shouldExposeMilestoneTool();
       const toolLines = [
         'LLM-callable tools:',
-        '  linear_issue (list/view/create/update/comment/start/delete)',
-        '  linear_project (list)',
+        '  linear_issue (list/view/activity/create/update/comment/start/delete)',
+        '  linear_project (list/view/create/update/delete/archive/unarchive)',
+        '  linear_project_update (list/view/create/update/archive/unarchive)',
         '  linear_team (list)',
       ];