@fink-andreas/pi-linear-tools 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.7.3 (2026-07-28)
+
+Patch release that fixes Linear issue-relation updates for OAuth users.
+
+### Bug Fixes
+- **Enable issue relations with default OAuth**: New OAuth grants now request Linear's `write` scope, allowing `linear_issue update` to set `blockedBy`, `blocking`, `relatedTo`, and `duplicateOf` relations.
+- **Explain legacy-token remediation**: Relation updates rejected because `write` is missing now direct OAuth users to run `pi-linear-tools auth login`; API-key users are told to use a key with write access.
+
+### Tests
+- Added regression coverage for the default OAuth authorization URL scope and issue-relation scope guidance.
+
+### Upgrade note
+Existing OAuth tokens cannot gain the newly requested scope automatically. Re-authenticate with `pi-linear-tools auth login` before creating issue relations.
+
 ## v0.7.2 (2026-07-21)
 
 Patch release for Pi package rename compatibility and terminal-safe fallback rendering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "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-render-fallback.js && node tests/test-issue-comment-result.js && node tests/test-issue-priority.js && node tests/test-settings.js && node tests/test-issue-download.js && node tests/test-api-usage-caching.js && node tests/test-issue-create-milestone.js && node tests/test-assignee-update.js && node tests/test-rate-limit-fallback-update.js && node tests/test-full-assignee-flow.js && node tests/test-branch-param.js && node tests/test-team-filter.js && node tests/test-project-crud.js && node tests/test-project-lifecycle.js && node tests/test-sync-doc.js && node tests/test-issue-activity.js",
+    "test": "node tests/test-package-manifest.js && node tests/test-oauth.js && node tests/test-extension-registration.js && node tests/test-render-fallback.js && node tests/test-issue-comment-result.js && node tests/test-issue-priority.js && node tests/test-settings.js && node tests/test-issue-download.js && node tests/test-api-usage-caching.js && node tests/test-issue-create-milestone.js && node tests/test-assignee-update.js && node tests/test-rate-limit-fallback-update.js && node tests/test-full-assignee-flow.js && node tests/test-branch-param.js && node tests/test-team-filter.js && node tests/test-project-crud.js && node tests/test-project-lifecycle.js && node tests/test-sync-doc.js && node tests/test-issue-activity.js",
     "dev:sync-local-extension": "node scripts/dev-sync-local-extension.mjs",
     "release:check": "npm test && npm pack --dry-run"
   },

package/src/auth/constants.js

@@ -5,5 +5,10 @@
 // Linear OAuth application client ID
 export const OAUTH_CLIENT_ID = 'a3e177176c6697611367f1a2405d4a34';
 
-// OAuth scopes - minimal required scopes
-export const OAUTH_SCOPES = ['read', 'issues:create', 'comments:create'];
+// OAuth scopes - minimal required scopes.
+// `write` is included so issue relations (blockedBy / blocking / relatedTo / duplicateOf) work:
+// those go through the `issueRelationCreate` mutation, which Linear gates behind the `write`
+// scope, whereas `issueUpdate` (title/description/state/assignee/parentId) is permitted under
+// `issues:create`. Without `write`, the `linear_issue` tool accepts the relation params but
+// Linear rejects them with "Invalid scope: `write` required". See upstream issue #27.
+export const OAUTH_SCOPES = ['read', 'issues:create', 'comments:create', 'write'];

package/src/error-hints.js

@@ -22,3 +22,30 @@ export function withMilestoneScopeHint(error) {
 
   return error;
 }
+
+/**
+ * Adds remediation guidance when an issue-relation mutation is rejected because
+ * an existing credential was issued before the default OAuth scopes included `write`.
+ *
+ * @param {Error} error - The error to wrap
+ * @param {object} patch - Requested issue update fields
+ * @returns {Error} The original error or a new error with additional hint
+ */
+export function withIssueRelationScopeHint(error, patch = {}) {
+  const message = String(error?.message || error || 'Unknown error');
+  const relationFields = ['blockedBy', 'blocking', 'relatedTo', 'duplicateOf'];
+  const requestsRelation = relationFields.some((field) => {
+    const value = patch[field];
+    return Array.isArray(value) ? value.length > 0 : String(value || '').trim() !== '';
+  });
+
+  if (requestsRelation && /invalid scope/i.test(message) && /write/i.test(message)) {
+    return new Error(
+      `${message}\nHint: Issue relations require Linear's write scope. ` +
+      `If you authenticated with OAuth before this scope was added, run ` +
+      '`pi-linear-tools auth login` to re-authenticate. API-key users need a key with write access.'
+    );
+  }
+
+  return error;
+}

package/src/handlers.js

@@ -46,6 +46,7 @@ import {
   withHandlerErrorHandling,
   getViewer,
 } from './linear.js';
+import { withIssueRelationScopeHint } from './error-hints.js';
 import { debug } from './logger.js';
 
 function toTextResult(text, details = {}) {
@@ -804,7 +805,12 @@ export async function executeIssueUpdate(client, params) {
     projectMilestoneId: updatePatch.projectMilestoneId,
   });
 
-  const result = await updateIssue(client, issue, updatePatch);
+  let result;
+  try {
+    result = await updateIssue(client, issue, updatePatch);
+  } catch (error) {
+    throw withIssueRelationScopeHint(error, updatePatch);
+  }
 
   const friendlyChanges = result.changed.map((field) => {
     if (field === 'stateId') return 'state';