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

package/src/linear.js

@@ -235,6 +235,45 @@ const PROJECT_UPDATE_MUTATION = `
   }
 `;
 
+
+const MILESTONE_DETAILS_QUERY = `
+  query MilestoneDetails($id: String!, $issueLimit: Int!) {
+    projectMilestone(id: $id) {
+      id
+      name
+      description
+      progress
+      sortOrder
+      targetDate
+      status
+      project {
+        id
+        name
+      }
+      issues(first: $issueLimit) {
+        nodes {
+          id
+          identifier
+          title
+          priority
+          estimate
+          state {
+            id
+            name
+            color
+            type
+          }
+          assignee {
+            id
+            name
+            displayName
+          }
+        }
+      }
+    }
+  }
+`;
+
 const PROJECT_DELETE_MUTATION = `
   mutation ProjectDelete($id: String!) {
     projectDelete(id: $id) {
@@ -249,7 +288,7 @@ const PROJECT_DELETE_MUTATION = `
 
 const PROJECT_ARCHIVE_MUTATION = `
   mutation ProjectArchive($id: String!) {
-    projectArchiveResult: projectDelete(id: $id) {
+    projectArchiveResult: projectArchive(id: $id) {
       success
       entity {
         id
@@ -1253,7 +1292,11 @@ async function fetchProjectMilestonesByQuery(client, projectId, options = {}) {
  * Track rate limit status from API responses
  * Linear API returns headers: X-RateLimit-Requests-Remaining, X-RateLimit-Requests-Reset
  */
+const DEFAULT_REQUEST_LIMIT = 5000;
+const LOW_RATE_LIMIT_THRESHOLD = 0.10;
+
 const rateLimitState = {
+  limit: DEFAULT_REQUEST_LIMIT,
   remaining: null,
   resetAt: null,
   lastWarnAt: 0,
@@ -1268,14 +1311,21 @@ function updateRateLimitState(response) {
 
   const headers = response.headers;
   if (headers) {
+    const limit = headers.get('X-RateLimit-Requests-Limit');
     const remaining = headers.get('X-RateLimit-Requests-Remaining');
     const resetAt = headers.get('X-RateLimit-Requests-Reset');
 
+    if (limit !== null) {
+      const parsedLimit = parseInt(limit, 10);
+      if (Number.isFinite(parsedLimit)) rateLimitState.limit = parsedLimit;
+    }
     if (remaining !== null) {
-      rateLimitState.remaining = parseInt(remaining, 10);
+      const parsedRemaining = parseInt(remaining, 10);
+      if (Number.isFinite(parsedRemaining)) rateLimitState.remaining = parsedRemaining;
     }
     if (resetAt !== null) {
-      rateLimitState.resetAt = parseInt(resetAt, 10);
+      const parsedResetAt = parseInt(resetAt, 10);
+      if (Number.isFinite(parsedResetAt)) rateLimitState.resetAt = parsedResetAt;
     }
   }
 }
@@ -1286,6 +1336,7 @@ function updateRateLimitState(response) {
  */
 export function getRateLimitStatus() {
   const result = {
+    limit: rateLimitState.limit,
     remaining: rateLimitState.remaining,
     resetAt: rateLimitState.resetAt,
     resetTime: null,
@@ -1296,9 +1347,10 @@ export function getRateLimitStatus() {
   if (rateLimitState.resetAt) {
     result.resetTime = new Date(rateLimitState.resetAt).toLocaleTimeString();
     const remaining = rateLimitState.remaining;
-    if (remaining !== null && remaining <= 1000) {
-      result.usagePercent = Math.round(((5000 - remaining) / 5000) * 100);
-      result.shouldWarn = remaining <= 500;
+    const limit = rateLimitState.limit || DEFAULT_REQUEST_LIMIT;
+    if (remaining !== null) {
+      result.usagePercent = Math.round((Math.max(0, limit - remaining) / limit) * 100);
+      result.shouldWarn = remaining <= Math.max(1, Math.floor(limit * LOW_RATE_LIMIT_THRESHOLD));
     }
   }
 
@@ -1317,6 +1369,7 @@ function checkRateLimitWarning() {
   if (status.shouldWarn && status.remaining !== null) {
     rateLimitState.lastWarnAt = now;
     warn(`Linear API rate limit running low: ${status.remaining} requests remaining (~${status.usagePercent}% used). Resets at ${status.resetTime}`, {
+      limit: status.limit,
       remaining: status.remaining,
       resetAt: status.resetTime,
       usagePercent: status.usagePercent,
@@ -1331,7 +1384,7 @@ function checkRateLimitWarning() {
  * @param {Error} error - The error to check
  * @returns {boolean}
  */
-function isLinearError(error) {
+export function isLinearError(error) {
   return error?.constructor?.name?.includes('LinearError') ||
     error?.name?.includes('LinearError') ||
     error?.type?.startsWith?.('Ratelimited') ||
@@ -1342,6 +1395,19 @@ function isLinearError(error) {
     error?.type === 'InternalError';
 }
 
+
+/**
+ * Check if an error is a rate-limit error
+ * @param {Error} error - The error to check
+ * @returns {boolean}
+ */
+export function isRateLimitError(error) {
+  return (
+    isLinearError(error) &&
+    (error?.type === 'Ratelimited' || String(error?.message || '').toLowerCase().includes('rate limit'))
+  );
+}
+
 /**
  * Format a Linear API error into a user-friendly message
  * @param {Error} error - The original error
@@ -1536,6 +1602,37 @@ function normalizeProjectUpdateHealth(value) {
   return normalized;
 }
 
+const ISSUE_PRIORITY_NAMES = ['No priority', 'Urgent', 'High', 'Medium', 'Low'];
+const ISSUE_PRIORITY_ALIASES = Object.freeze({
+  none: 0,
+  urgent: 1,
+  high: 2,
+  medium: 3,
+  low: 4,
+});
+const ISSUE_PRIORITY_MAPPING_DESCRIPTION = '0=None, 1=Urgent, 2=High, 3=Medium, 4=Low';
+const ISSUE_PRIORITY_ALIAS_DESCRIPTION = Object.keys(ISSUE_PRIORITY_ALIASES).join(', ');
+
+function parseIssuePriority(value) {
+  if (typeof value === 'number') {
+    if (Number.isInteger(value) && value >= 0 && value <= 4) {
+      return value;
+    }
+  } else if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(ISSUE_PRIORITY_ALIASES, normalized)) {
+      return ISSUE_PRIORITY_ALIASES[normalized];
+    }
+    if (/^[0-4]$/.test(normalized)) {
+      return Number(normalized);
+    }
+  }
+
+  throw new Error(
+    `Invalid priority: ${value}. Use Linear priority ${ISSUE_PRIORITY_MAPPING_DESCRIPTION}, or one of: ${ISSUE_PRIORITY_ALIAS_DESCRIPTION}.`
+  );
+}
+
 function formatPriorityLabel(value) {
   if (value === undefined || value === null) {
     return null;
@@ -1546,8 +1643,7 @@ function formatPriorityLabel(value) {
     return String(value);
   }
 
-  const priorityNames = ['No priority', 'Urgent', 'High', 'Medium', 'Low'];
-  return priorityNames[numeric] || `Priority ${numeric}`;
+  return ISSUE_PRIORITY_NAMES[numeric] || `Priority ${numeric}`;
 }
 
 function getUserDisplayName(user) {
@@ -2807,6 +2903,145 @@ export async function fetchIssueDetails(client, issueRef, options = {}) {
   }, 'fetchIssueDetails');
 }
 
+function extractMarkdownImages(markdown, source) {
+  if (!markdown || typeof markdown !== 'string') return [];
+
+  const images = [];
+  const markdownImagePattern = /!\[([^\]]*)\]\(([^\s)]+)(?:\s+"[^"]*")?\)/g;
+  const htmlImagePattern = /<img\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/gi;
+
+  let match;
+  while ((match = markdownImagePattern.exec(markdown)) !== null) {
+    images.push({ alt: match[1] || null, url: match[2], source });
+  }
+  while ((match = htmlImagePattern.exec(markdown)) !== null) {
+    images.push({ alt: null, url: match[1], source });
+  }
+
+  return images;
+}
+
+function isImageUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function isLinearUploadUrl(url) {
+  try {
+    const hostname = new URL(url).hostname.toLowerCase();
+    return hostname === 'uploads.linear.app' || hostname.endsWith('.uploads.linear.app');
+  } catch {
+    return false;
+  }
+}
+
+function getLinearAuthHeaderValue(client, mode = 'raw') {
+  const token = client?.__piLinearTrackerKey || client?.apiKey || null;
+  if (!token || token === 'default') return null;
+  return mode === 'bearer' ? `Bearer ${token}` : token;
+}
+
+async function fetchImageUrl(client, url, options = {}) {
+  const { maxBytes = 10 * 1024 * 1024 } = options;
+  const attempts = [{ headers: {} }];
+
+  if (isLinearUploadUrl(url)) {
+    const rawAuth = getLinearAuthHeaderValue(client, 'raw');
+    const bearerAuth = getLinearAuthHeaderValue(client, 'bearer');
+    if (rawAuth) attempts.push({ headers: { authorization: rawAuth } });
+    if (bearerAuth) attempts.push({ headers: { authorization: bearerAuth } });
+  }
+
+  let lastError = null;
+  for (const attempt of attempts) {
+    try {
+      const response = await fetch(url, { headers: attempt.headers, redirect: 'follow' });
+      if (!response.ok) {
+        lastError = new Error(`HTTP ${response.status} ${response.statusText}`);
+        continue;
+      }
+
+      const contentType = response.headers.get('content-type') || 'application/octet-stream';
+      if (!contentType.toLowerCase().startsWith('image/')) {
+        lastError = new Error(`URL did not return an image (content-type: ${contentType})`);
+        continue;
+      }
+
+      const contentLength = Number(response.headers.get('content-length') || 0);
+      if (contentLength > maxBytes) {
+        throw new Error(`Image is too large (${contentLength} bytes, max ${maxBytes})`);
+      }
+
+      const buffer = Buffer.from(await response.arrayBuffer());
+      if (buffer.length > maxBytes) {
+        throw new Error(`Image is too large (${buffer.length} bytes, max ${maxBytes})`);
+      }
+
+      return {
+        data: buffer.toString('base64'),
+        mimeType: contentType.split(';')[0].trim() || 'application/octet-stream',
+        sizeBytes: buffer.length,
+      };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  throw lastError || new Error('Failed to fetch image');
+}
+
+export async function fetchIssueImages(client, issueRef, options = {}) {
+  return withLinearErrorHandling(async () => {
+    const { includeComments = true, limit = 10, maxBytes = 10 * 1024 * 1024 } = options;
+    const issueData = await fetchIssueDetails(client, issueRef, { includeComments });
+    const candidates = [];
+
+    candidates.push(...extractMarkdownImages(issueData.description, 'description'));
+    if (includeComments) {
+      for (const comment of issueData.comments || []) {
+        candidates.push(...extractMarkdownImages(comment.body, `comment:${comment.id}`));
+      }
+    }
+
+    const seen = new Set();
+    const uniqueCandidates = candidates
+      .filter((candidate) => candidate.url && isImageUrl(candidate.url))
+      .filter((candidate) => {
+        if (seen.has(candidate.url)) return false;
+        seen.add(candidate.url);
+        return true;
+      })
+      .slice(0, limit);
+
+    const images = [];
+    const failures = [];
+    for (const candidate of uniqueCandidates) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const image = await fetchImageUrl(client, candidate.url, { maxBytes });
+        images.push({ ...candidate, ...image });
+      } catch (error) {
+        failures.push({ ...candidate, error: error?.message || String(error) });
+      }
+    }
+
+    return {
+      issue: {
+        identifier: issueData.identifier,
+        title: issueData.title,
+        url: issueData.url,
+      },
+      images,
+      failures,
+      totalCandidates: candidates.length,
+    };
+  }, 'fetchIssueImages');
+}
+
 export async function fetchIssueActivity(client, issueRef, options = {}) {
   return withLinearErrorHandling(async () => {
     const limit = normalizePositiveInteger(options.limit, 'limit', 20);
@@ -2913,7 +3148,7 @@ export async function setIssueState(client, issueId, stateId) {
  * @param {string} input.title - Issue title (required)
  * @param {string} [input.description] - Issue description
  * @param {string} [input.projectId] - Project ID
- * @param {string} [input.priority] - Priority 0-4
+ * @param {number|string} [input.priority] - Issue priority: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low; or none/urgent/high/medium/low
  * @param {string} [input.assigneeId] - Assignee ID
  * @param {string} [input.parentId] - Parent issue ID for sub-issues
  * @returns {Promise<Object>} Created issue
@@ -2944,11 +3179,7 @@ export async function createIssue(client, input) {
     }
 
     if (input.priority !== undefined) {
-      const parsed = Number.parseInt(String(input.priority), 10);
-      if (Number.isNaN(parsed) || parsed < 0 || parsed > 4) {
-        throw new Error(`Invalid priority: ${input.priority}. Valid range: 0..4`);
-      }
-      createInput.priority = parsed;
+      createInput.priority = parseIssuePriority(input.priority);
     }
 
     if (input.estimate !== undefined) {
@@ -3010,7 +3241,7 @@ export async function createIssue(client, input) {
         title,
         description: input.description ?? null,
         url: null,
-        priority: input.priority ?? null,
+        priority: createInput.priority ?? null,
         state: null,
         team: null,
         project: null,
@@ -3024,7 +3255,7 @@ export async function createIssue(client, input) {
       title,
       description: input.description ?? null,
       url: null,
-      priority: input.priority ?? null,
+      priority: createInput.priority ?? null,
       state: null,
       team: null,
       project: null,
@@ -3157,11 +3388,7 @@ export async function updateIssue(client, issueRef, patch = {}) {
     }
 
     if (patch.priority !== undefined) {
-      const parsed = Number.parseInt(String(patch.priority), 10);
-      if (Number.isNaN(parsed) || parsed < 0 || parsed > 4) {
-        throw new Error(`Invalid priority: ${patch.priority}. Valid range: 0..4`);
-      }
-      updateInput.priority = parsed;
+      updateInput.priority = parseIssuePriority(patch.priority);
     }
 
 
@@ -3527,24 +3754,90 @@ export async function fetchProjectMilestones(client, projectId) {
  */
 export async function fetchMilestoneDetails(client, milestoneId) {
   return withLinearErrorHandling(async () => {
+    // Prefer raw GraphQL: one request instead of N+1 SDK lazy loads.
+    // This dramatically reduces rate-limit exposure for milestone view.
+    if (getRawRequest(client)) {
+      try {
+        const data = await executeGraphQL(client, MILESTONE_DETAILS_QUERY, {
+          id: milestoneId,
+          issueLimit: 250,
+        });
+
+        const raw = data?.projectMilestone;
+        if (!raw) {
+          throw new Error(`Milestone not found: ${milestoneId}`);
+        }
+
+        const project = raw.project ? { id: raw.project.id, name: raw.project.name } : null;
+        const issues = (raw.issues?.nodes || []).map((issue) => ({
+          id: issue.id,
+          identifier: issue.identifier,
+          title: issue.title,
+          state: issue.state ? { name: issue.state.name, color: issue.state.color, type: issue.state.type } : null,
+          assignee: issue.assignee ? { id: issue.assignee.id, name: issue.assignee.name, displayName: issue.assignee.displayName } : null,
+          priority: issue.priority ?? null,
+          estimate: issue.estimate ?? null,
+        }));
+
+        return {
+          id: raw.id,
+          name: raw.name,
+          description: raw.description ?? null,
+          progress: raw.progress ?? null,
+          order: raw.sortOrder ?? null,
+          targetDate: raw.targetDate ?? null,
+          status: raw.status ?? null,
+          project,
+          issues,
+        };
+      } catch (err) {
+        // If raw GraphQL fails (e.g., network error), fall through to SDK path.
+        // Rate-limit errors are re-thrown by executeGraphQL -> withLinearErrorHandling.
+        if (!isLinearError(err)) {
+          debug('fetchMilestoneDetails: raw GraphQL unavailable, falling back to SDK', { error: err?.message });
+        } else {
+          throw err; // re-throw Linear errors including rate limits
+        }
+      }
+    }
+
+    // SDK fallback: the rate-limit propagation logic for lazy loads is preserved.
     const milestone = await client.projectMilestone(milestoneId);
     if (!milestone) {
       throw new Error(`Milestone not found: ${milestoneId}`);
     }
 
     // Fetch project and issues in parallel
-    const [project, issuesResult] = await Promise.all([
+    const [projectResult, issuesResult] = await Promise.all([
       milestone.project?.catch?.(() => null) ?? milestone.project,
-      milestone.issues?.()?.catch?.(() => ({ nodes: [] })) ?? milestone.issues?.() ?? { nodes: [] },
+      milestone.issues?.()?.catch?.((err) => {
+        if (isRateLimitError(err)) {
+          // Propagate rate-limit errors so the caller can surface a safe user message
+          // instead of silently swallowing the issue list.
+          throw err;
+        }
+        return { nodes: [] };
+      }) ?? { nodes: [] },
     ]);
 
+    const project = projectResult;
+
     const issues = await Promise.all(
       (issuesResult.nodes || []).map(async (issue) => {
+        // Propagate rate-limit errors from per-issue lazy loads so the caller can surface
+        // a safe user message. Silently degrading to partial data masks the problem.
         const [state, assignee] = await Promise.all([
-          issue.state?.catch?.(() => null) ?? issue.state,
-          issue.assignee?.catch?.(() => null) ?? issue.assignee,
+          issue.state?.catch?.((err) => {
+            if (isRateLimitError(err)) throw err;
+            return null;
+          }) ?? issue.state,
+          issue.assignee?.catch?.((err) => {
+            if (isRateLimitError(err)) throw err;
+            return null;
+          }) ?? issue.assignee,
         ]);
 
+
         return {
           id: issue.id,
           identifier: issue.identifier,

package/src/settings.js

@@ -21,6 +21,8 @@ export function getDefaultSettings() {
     defaultTeam: null,
     defaultWorkspace: null,
     projects: {},
+    rateLimitDebug: false, // Enable detailed rate limit info per tool call
+    allow_overwrite_files: false, // Require explicit opt-in before tools can overwrite local files
   };
 }
 
@@ -111,6 +113,16 @@ function migrateSettings(settings) {
     migrated.projects = {};
   }
 
+  // Ensure rateLimitDebug is a boolean
+  if (migrated.rateLimitDebug === undefined) {
+    migrated.rateLimitDebug = false;
+  }
+
+  // Ensure local file overwrite guard is disabled by default
+  if (migrated.allow_overwrite_files === undefined) {
+    migrated.allow_overwrite_files = false;
+  }
+
   // Migrate project scopes
   for (const [projectId, cfg] of Object.entries(migrated.projects)) {
     if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) {
@@ -216,6 +228,16 @@ export function validateSettings(settings) {
     }
   }
 
+  // Validate rateLimitDebug
+  if (settings.rateLimitDebug !== undefined && typeof settings.rateLimitDebug !== 'boolean') {
+    errors.push('settings.rateLimitDebug must be a boolean');
+  }
+
+  // Validate local file overwrite guard
+  if (settings.allow_overwrite_files !== undefined && typeof settings.allow_overwrite_files !== 'boolean') {
+    errors.push('settings.allow_overwrite_files must be a boolean');
+  }
+
   return { valid: errors.length === 0, errors };
 }