@fink-andreas/pi-linear-tools 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -1,20 +1,42 @@
 # Changelog
 
-## v0.4.3 (2026-04-02)
+## v0.5.1 (2026-04-17)
 
-Sync-doc parity and tool prompt metadata polish release.
+### Bug Fixes
+- **Prevent pi crashes from Linear tool errors**: Added `executeToolSafely` wrapper that catches errors and returns them as safe tool results instead of throwing, preventing pi from crashing on Linear API errors
+
+## v0.5.0 (2026-04-17)
+
+Linear document sync, project lifecycle management, and estimate/story points support.
+
+### New Features
+- **Linear document sync**: Keep Linear documents in sync with local Markdown files via `linear_doc_sync` command
+- **Project lifecycle**: Full project lifecycle support including archive/unarchive, updates, and milestones
+- **Estimate (story points)**: Support for estimate/story points field on issue create/update
+- **Issue activity history**: View complete issue activity with `linear_issue_activity` tool
+- **Batch sync**: `sync-doc --all` for batch syncing all configured document targets
 
 ### Bug Fixes
-- Fixed first-run `sync-doc` batch parity so `check` and `run` produce aligned project index planning
-- Preserved existing managed marker location when `position` is `top`
-- Resolved archived projects more reliably during project update flows
+- Fixed project name lookup for UUID-like project names
+- Fixed milestone name lookup for view/update/delete operations
+- Replaced 'order' with 'sortOrder' for ProjectMilestone queries
+- Fixed sync-doc first-run check/run parity
+- Fixed sync-doc drift detection and target matching
+- Fixed project archive and update validation
+- Fixed archived project resolution for project updates
+- Fixed sync-doc marker position preservation when position is 'top'
+- Fixed default limit for executeIssueActivity (now 25)
 
 ### Improvements
-- Added `promptSnippet` metadata consistently across all Linear tools for better in-app tool discoverability/context
-- Added default activity limit handling for issue activity execution paths
-
-### Tests
-- Added/updated sync-doc regression coverage for first-run check/run parity and marker placement stability
+- Reduced expensive Linear API issue reads
+- Better CLI help for issue and project workflows
+- Improved sync-doc examples and guidance
+- Added promptSnippet to all Linear tools for consistent LLM context
+- Removed redundant action lists from tool descriptions
+
+### Cleanup
+- Removed planning artifacts and documentation files
+- Stopped tracking plan files in git
 
 ## v0.4.2 (2026-03-26)
 

package/extensions/pi-linear-tools.js

@@ -452,6 +452,85 @@ 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 buildGenericToolErrorResult(error, operationLabel) {
+  const errorType = error?.type || error?.name || 'Error';
+  const errorMessage = String(error?.message || error || 'Unknown error');
+
+  return toToolTextResult(`${operationLabel}: ${errorMessage}`, {
+    error: true,
+    errorType,
+    rateLimited: false,
+  });
+}
+
+async function executeToolSafely(operationLabel, operation, options = {}) {
+  try {
+    return await operation();
+  } catch (error) {
+    debug('[pi-linear-tools] tool execution failed', {
+      operationLabel,
+      errorType: error?.type || error?.name || null,
+      error: String(error?.message || error || 'unknown'),
+    });
+
+    try {
+      return handleToolExecutionError(error, operationLabel, options);
+    } catch (handledError) {
+      debug('[pi-linear-tools] returning generic safe tool error result', {
+        operationLabel,
+        errorType: handledError?.type || handledError?.name || null,
+        error: String(handledError?.message || handledError || 'unknown'),
+      });
+      return buildGenericToolErrorResult(handledError, operationLabel);
+    }
+  }
+}
+
 function renderMarkdownResult(result, _options, _theme) {
   const text = result.content?.[0]?.text || '';
 
@@ -491,7 +570,7 @@ async function registerLinearTools(pi) {
   pi.registerTool({
     name: 'linear_issue',
     label: 'Linear Issue',
-    description: 'Interact with Linear issues. Actions: list, view, activity, 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',
@@ -586,6 +665,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)',
@@ -617,17 +700,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.`
-        );
-      }
+      return executeToolSafely('Linear issue operation failed', async () => {
+        // 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 });
+        }
 
-      try {
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_issue', params.action, async () => {
@@ -656,63 +735,14 @@ async function registerLinearTools(pi) {
               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}`);
-      }
+      });
     },
   });
 
   pi.registerTool({
     name: 'linear_project',
     label: 'Linear Project',
-    description: 'Interact with Linear projects. Actions: list, view, create, update, delete, archive, unarchive',
+    description: 'Interact with Linear projects.',
     promptSnippet: 'Interact with Linear projects (list, view, create, update, delete, archive, unarchive)',
     parameters: {
       type: 'object',
@@ -771,7 +801,7 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      try {
+      return executeToolSafely('Linear project operation failed', async () => {
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_project', params.action, async () => {
@@ -794,31 +824,14 @@ async function registerLinearTools(pi) {
               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.`);
-        }
-
-        if (errorMessage.includes('Linear API error:')) {
-          throw error;
-        }
-
-        throw new Error(`Linear project operation failed: ${errorMessage}`);
-      }
+      });
     },
   });
 
   pi.registerTool({
     name: 'linear_project_update',
     label: 'Linear Project Update',
-    description: 'Interact with Linear project updates. Actions: list, view, create, update, archive, unarchive',
+    description: 'Interact with Linear project updates.',
     promptSnippet: 'Interact with Linear project updates (list, view, create, update, archive, unarchive)',
     parameters: {
       type: 'object',
@@ -865,7 +878,7 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      try {
+      return executeToolSafely('Linear project update operation failed', async () => {
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_project_update', params.action, async () => {
@@ -886,30 +899,14 @@ async function registerLinearTools(pi) {
               throw new Error(`Unknown action: ${params.action}`);
           }
         });
-      } catch (error) {
-        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 project update operation failed: ${errorMessage}`);
-      }
+      });
     },
   });
 
   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',
@@ -925,7 +922,7 @@ async function registerLinearTools(pi) {
     },
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      try {
+      return executeToolSafely('Linear team operation failed', async () => {
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_team', params.action, async () => {
@@ -936,24 +933,7 @@ async function registerLinearTools(pi) {
               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.`);
-        }
-
-        if (errorMessage.includes('Linear API error:')) {
-          throw error;
-        }
-
-        throw new Error(`Linear team operation failed: ${errorMessage}`);
-      }
+      });
     },
   });
 
@@ -961,7 +941,7 @@ 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',
@@ -997,7 +977,7 @@ async function registerLinearTools(pi) {
       },
       renderResult: renderMarkdownResult,
       async execute(_toolCallId, params) {
-        try {
+        return executeToolSafely('Linear milestone operation failed', async () => {
           const client = await createAuthenticatedClient();
 
           return await withRequestUsageLogging(client, 'linear_milestone', params.action, async () => {
@@ -1016,26 +996,9 @@ async function registerLinearTools(pi) {
                 throw new Error(`Unknown action: ${params.action}`);
             }
           });
-        } 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}`);
-        }
+        }, {
+          transformError: withMilestoneScopeHint,
+        });
       },
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Pi extension with Linear SDK tools and configuration commands",
   "type": "module",
   "engines": {

package/src/handlers.js

@@ -17,6 +17,7 @@ import {
   fetchTeams,
   resolveProjectRef,
   resolveTeamRef,
+  resolveMilestoneRef,
   getTeamWorkflowStates,
   fetchIssueDetails,
   fetchIssueActivity,
@@ -319,6 +320,10 @@ export async function executeIssueCreate(client, params, options = {}) {
     createInput.priority = params.priority;
   }
 
+  if (params.estimate !== undefined && params.estimate !== null) {
+    createInput.estimate = params.estimate;
+  }
+
   if (params.parentId) {
     createInput.parentId = params.parentId;
   }
@@ -401,6 +406,7 @@ export async function executeIssueUpdate(client, params) {
     title: params.title,
     description: params.description,
     priority: params.priority,
+    estimate: params.estimate,
     state: params.state,
     milestone: params.milestone,
     projectMilestoneId: params.projectMilestoneId,
@@ -1041,7 +1047,24 @@ export async function executeMilestoneList(client, params) {
  * View milestone details
  */
 export async function executeMilestoneView(client, params) {
-  const milestoneId = ensureNonEmpty(params.milestone, 'milestone');
+  let projectId = null;
+  let milestoneId = params.milestone;
+
+  // If milestone is not a Linear ID, resolve it with project context
+  const ref = String(milestoneId || '').trim();
+  const isId = typeof ref === 'string' && /^[0-9a-fA-F-]{16,}$/.test(ref);
+
+  if (!isId) {
+    // Need project context to resolve milestone name
+    let projectRef = params.project;
+    if (!projectRef) {
+      projectRef = path.basename(process.cwd());
+    }
+    const resolvedProject = await resolveProjectRef(client, projectRef);
+    projectId = resolvedProject.id;
+    const resolvedMilestone = await resolveMilestoneRef(client, ref, projectId);
+    milestoneId = resolvedMilestone.id;
+  }
 
   const milestoneData = await fetchMilestoneDetails(client, milestoneId);
 
@@ -1163,7 +1186,25 @@ export async function executeMilestoneCreate(client, params) {
  * Update a milestone
  */
 export async function executeMilestoneUpdate(client, params) {
-  const milestoneId = ensureNonEmpty(params.milestone, 'milestone');
+  let projectId = null;
+  let milestoneId = params.milestone;
+
+  // If milestone is not a Linear ID, resolve it with project context
+  const ref = String(milestoneId || '').trim();
+  const isId = typeof ref === 'string' && /^[0-9a-fA-F-]{16,}$/.test(ref);
+
+
+  if (!isId) {
+    // Need project context to resolve milestone name
+    let projectRef = params.project;
+    if (!projectRef) {
+      projectRef = path.basename(process.cwd());
+    }
+    const resolvedProject = await resolveProjectRef(client, projectRef);
+    projectId = resolvedProject.id;
+    const resolvedMilestone = await resolveMilestoneRef(client, ref, projectId);
+    milestoneId = resolvedMilestone.id;
+  }
 
   // Note: status is not included as it's a computed/read-only field in Linear's API
   const result = await updateProjectMilestone(client, milestoneId, {
@@ -1202,7 +1243,26 @@ export async function executeMilestoneUpdate(client, params) {
  * Delete a milestone
  */
 export async function executeMilestoneDelete(client, params) {
-  const milestoneId = ensureNonEmpty(params.milestone, 'milestone');
+  let projectId = null;
+  let milestoneId = params.milestone;
+
+  // If milestone is not a Linear ID, resolve it with project context
+  const ref = String(milestoneId || '').trim();
+  const isId = typeof ref === 'string' && /^[0-9a-fA-F-]{16,}$/.test(ref);
+
+
+  if (!isId) {
+    // Need project context to resolve milestone name
+    let projectRef = params.project;
+    if (!projectRef) {
+      projectRef = path.basename(process.cwd());
+    }
+    const resolvedProject = await resolveProjectRef(client, projectRef);
+    projectId = resolvedProject.id;
+    const resolvedMilestone = await resolveMilestoneRef(client, ref, projectId);
+    milestoneId = resolvedMilestone.id;
+  }
+
   const result = await deleteProjectMilestone(client, milestoneId);
 
   const label = result.name