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

package/CHANGELOG.md

@@ -1,20 +1,37 @@
 # Changelog
 
-## v0.4.3 (2026-04-02)
+## v0.5.0 (2026-04-17)
 
-Sync-doc parity and tool prompt metadata polish release.
+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,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 || '';
 
@@ -491,7 +536,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 +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)',
@@ -617,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 () => {
@@ -661,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')) {
@@ -698,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');
       }
     },
   });
@@ -712,7 +739,7 @@ async function registerLinearTools(pi) {
   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',
@@ -795,22 +822,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 project operation failed: ${errorMessage}`);
+        return handleToolExecutionError(error, 'Linear project operation failed');
       }
     },
   });
@@ -818,7 +830,7 @@ async function registerLinearTools(pi) {
   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',
@@ -887,21 +899,7 @@ async function registerLinearTools(pi) {
           }
         });
       } 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}`);
+        return handleToolExecutionError(error, 'Linear project update operation failed');
       }
     },
   });
@@ -909,7 +907,7 @@ 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',
@@ -937,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');
       }
     },
   });
@@ -961,7 +944,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',
@@ -1017,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,
+          });
         }
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "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