feat(linear): add Linear GraphQL API client

[aaight]

Summary

• Creates src/linear/types.ts with full type definitions: LinearCredentials, LinearIssue, LinearComment, LinearLabel, LinearTeam, LinearUser, LinearWorkflowState, LinearAttachment, LinearReaction, LinearWebhookPayload, and input types
• Creates src/linear/client.ts with withLinearCredentials() using AsyncLocalStorage — matching the pattern from src/trello/client.ts and src/jira/client.ts
• Implements linearClient with all required methods: getIssue, listIssues, createIssue, updateIssue, updateIssueState, getIssueComments, createComment, updateComment, deleteComment, addLabel, removeLabel, getAttachments, createAttachment, createReaction, getMe
• All API calls target https://api.linear.app/graphql with Authorization: Bearer <api_key> header

Key Decisions

• AsyncLocalStorage pattern: withLinearCredentials() wraps async context exactly like withTrelloCredentials() / withJiraCredentials() — credential scoping is per-request, not global
• GraphQL fetch helper: A single linearGraphQL<T>() function handles POST, auth header injection, HTTP error detection, and GraphQL error propagation
• Typed response mappers: mapIssue, mapComment, mapUser, mapLabel, mapState, mapTeam — all convert raw GraphQL responses to typed domain objects, with safe ?? '' fallbacks
• Named raw types: RawIssue and RawComment interfaces reduce cognitive complexity (biome max=15) while keeping mappers clean
• Label management: addLabel/removeLabel fetch current label IDs first and use labelIds field to perform atomic updates

Test plan

• TypeScript compiles with zero errors (npx tsc --noEmit)
• Lint passes with zero errors (npx biome check src/linear/)
• Existing unit tests pass (npx vitest run tests/unit/worker-entry.test.ts, repo-hygiene, architecture-docs)

Links

• Trello card: https://trello.com/c/S0QHqsN5/592-as-a-developer-i-want-a-linear-api-client-so-that-cascade-can-communicate-with-linears-graphql-api

🤖 Generated with Claude Code

🕵️ claude-code · claude-sonnet-4-6 · run details

[aaight]

CI Failures Resolved

Fixes Applied

• Critical axios vulnerability (SSRF): Added "axios": "^1.15.0" to package.json overrides to force all transitive dependents (jira.js, trello.js) to use axios ≥1.15.0, resolving GHSA-3p68-rc4w-qgx5 and GHSA-fvcv-3m26-pcqx (critical SSRF vulnerabilities) that were failing the npm audit --omit=dev --audit-level=high CI check.

Root Cause

The pre-existing axios@1.13.5 transitive dependency (pulled in by jira.js and trello.js) had critical SSRF vulnerabilities. The npm audit step in CI with --audit-level=high was failing because of this critical-severity finding. This was a pre-existing issue on the dev branch that surfaced in this PR's CI run.

Verification

• npm audit --omit=dev --audit-level=high exits 0 ✓ (critical vuln resolved)
• TypeScript compiles with zero errors ✓
• Lint passes with zero warnings/errors ✓
• All 7248 unit tests pass across 370 test files ✓
• Changes pushed to branch ✓

🕵️ claude-code · claude-sonnet-4-6 · run details

[codecov]

Codecov Report

❌ Patch coverage is 0% with 283 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/linear/client.ts	0.00%	283 Missing ⚠️

📢 Thoughts on this report? Let us know!

[nhopeatall]

Summary

Solid first step for Linear integration — the API client follows established patterns (AsyncLocalStorage credentials, mapper functions, GraphQL helper). A few issues worth addressing before building higher layers on top of this client.

Architecture & Design

• [SHOULD_FIX] LinearUpdateIssueInput is incomplete: addLabel and removeLabel pass { labelIds: [...] } as the GraphQL input, but labelIds is missing from the LinearUpdateIssueInput type definition. This works at runtime because the variables go through Record<string, unknown>, but it means: (1) callers of updateIssue() can't set labels through the typed API, and (2) the type doesn't accurately represent what the GraphQL mutation accepts. labelIds should be added to LinearUpdateIssueInput and the label methods should ideally delegate to updateIssue() rather than calling linearGraphQL directly.

• [SHOULD_FIX] Unrelated axios override bundled into this PR: The package.json and package-lock.json changes add an axios: "^1.15.0" override that's completely unrelated to the Linear GraphQL client (which uses fetch). This should be a separate PR to keep the change atomic and reviewable.

Code Issues

Should Fix

• src/linear/client.ts:407-417 — deleteComment ignores the success field returned by the GraphQL mutation. If Linear returns { success: false } (e.g., comment already deleted, permission denied), the method will silently succeed. Should check the response and throw if success is false.

• src/linear/types.ts:93-99 — LinearUpdateIssueInput is missing labelIds?: string[]. The addLabel/removeLabel methods in the client pass labelIds in the mutation input, proving the field is valid for IssueUpdateInput on the GraphQL side. The TypeScript type should reflect this so consumers can use updateIssue() for label changes.

• src/linear/client.ts:421-457 — addLabel/removeLabel use a read-then-update pattern (fetch issue, modify label list, send update). This is a TOCTOU race — if two concurrent calls add/remove labels on the same issue, one will overwrite the other's changes. This is a known limitation of Linear's API (no atomic add/remove label endpoints), but it should be documented with a comment so future maintainers don't accidentally assume these operations are atomic.

Observations (non-blocking)

• No unit tests are included for the Linear client. The Trello and JIRA clients also appear to lack dedicated client unit tests, so this is consistent — but as more methods build on this client, tests for the mapper functions and error handling paths would add confidence.

• getIssueComments doesn't support pagination. For issues with many comments this could be limiting, but it's consistent with how the JIRA client handles comments and acceptable for an initial implementation.

🕵️ claude-code · claude-opus-4-6 · run details

[aaight]

CI Failures Resolved

Root Cause

The lint-and-test CI check was failing at the Audit production dependencies step. The npm audit detected a critical severity vulnerability in axios <=1.14.0 (GHSA-3p68-rc4w-qgx5: SSRF via NO_PROXY bypass, GHSA-fvcv-3m26-pcqx: unrestricted cloud metadata exfiltration). Axios is a transitive dependency pulled in by jira.js and trello.js.

Fix Applied

Re-added the "axios": "^1.15.0" override to package.json's overrides section, which had been inadvertently reverted in the previous commit. This forces all transitive dependents to use a patched version of axios.

Verification

• ✅ npm audit --omit=dev --audit-level=high exits 0 (no high/critical vulnerabilities)
• ✅ npm run lint passes (2 pre-existing warnings, no errors)
• ✅ npm run typecheck passes (zero errors)
• ✅ npm run test:coverage passes (7248 tests, 370 files)
• ✅ Changes pushed to branch

🕵️ claude-code · claude-sonnet-4-6 · run details

[nhopeatall]

Summary

LGTM — Clean, well-structured Linear GraphQL API client that correctly follows the established AsyncLocalStorage credential-scoping pattern from the Trello and JIRA clients.

Notes

Pattern consistency: The AsyncLocalStorage + withLinearCredentials() pattern, the linearClient object structure, the mapper approach, and the module layout (types.ts + client.ts) all match the existing conventions in src/trello/ and src/jira/.

No unit tests: The PR description acknowledges that existing tests pass, but there are no new tests for the Linear client. This is acceptable for a pure API client where tests would be integration-level, but worth adding mock-based unit tests for the mappers and error handling paths as follow-up.

No integration wiring yet: The client module exists in isolation — there's no LinearIntegration class, no bootstrap registration, no credential roles registration, and no webhook route. The src/integrations/README.md already documents exactly how to wire Linear up (it uses Linear as its example). This is fine as a standalone first step if the integration wiring is planned for a follow-up PR.

Minor observations (not blocking):

• src/linear/client.ts:446 — removeLabel always calls updateIssue even when the label isn't present on the issue, while addLabel has an early-return optimization when the label is already present. Consider adding a symmetric early-return: if (!issue.labels.some(l => l.id === labelId)) return issue;
• getIssueComments and getAttachments don't pass a first parameter and don't handle pagination — Linear's default page size (typically 50) will silently truncate results for issues with many comments/attachments. Fine for now but worth noting for future use.
• The axios override bump (1.13.5 → 1.15.0) is a separate concern but reasonable to include.

🕵️ claude-code · claude-opus-4-6 · run details

[zbigniewsobiecki]

@aaight check out the CI and see what's up

[aaight]

CI Status: All Green ✅

Checked the CI — all 7 checks are passing:

Check	Status
lint-and-test	✅ success
validate-commits	✅ success
integration-tests	✅ success
Validate Docker builds	✅ success
Analyze (javascript-typescript)	✅ success
Analyze (actions)	✅ success
enforce-dev-to-main	⏭️ skipped (expected)

What happened earlier

The lint-and-test job was previously failing at the Audit production dependencies step because axios ≤1.14.0 (a transitive dependency pulled in by jira.js and trello.js) had two critical SSRF vulnerabilities:

• GHSA-3p68-rc4w-qgx5 — SSRF via NO_PROXY bypass
• GHSA-fvcv-3m26-pcqx — unrestricted cloud metadata exfiltration

This was a pre-existing issue on the dev branch that surfaced in this PR's CI run. It was resolved by adding "axios": "^1.15.0" to package.json's overrides section, forcing all transitive dependents to use the patched version.

No action needed — CI is clean and the PR is ready to merge.

🕵️ claude-code · claude-sonnet-4-6 · run details