Linear API token from settings.local.json not used by CLI commands

[acreeger]

Problem

When using Linear as the issue management provider, the LINEAR_API_TOKEN configured in settings.local.json is not read by CLI commands like il a (add-issue).

The settings schema supports storing the token:

// .iloom/settings.local.json
{
  "issueManagement": {
    "provider": "linear",
    "linear": {
      "teamId": "PROD",
      "apiToken": "lin_api_..."
    }
  }
}

However, the Linear SDK wrapper (src/utils/linear.ts) only checks process.env.LINEAR_API_TOKEN:

function getLinearApiToken(): string {
  const token = process.env.LINEAR_API_TOKEN
  if (!token) {
    throw new LinearServiceError(
      'UNAUTHORIZED',
      'LINEAR_API_TOKEN not set. Configure in settings.local.json or set environment variable.',
    )
  }
  return token
}

The error message suggests configuring in settings.local.json, but that path doesn't actually work.

Reproduction

1. Configure Linear in .iloom/settings.local.json with apiToken
2. Ensure LINEAR_API_TOKEN is NOT set in environment (unset LINEAR_API_TOKEN)
3. Run il a "some issue description"
4. Observe error: LINEAR_API_TOKEN not set. Configure in settings.local.json or set environment variable.

Notes

• The MCP server flow (src/utils/mcp.ts:79-82) does read from settings and passes it through, but direct CLI commands don't
• The IssueTrackerFactory.create() receives settings but doesn't pass the token to where it's needed

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 2
• Estimated lines of code: 40
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good (well-structured utility functions)
• Overall risk level: Low

Reasoning: The fix requires modifying only the getLinearApiToken() function in src/utils/linear.ts to check settings.issueManagement?.linear?.apiToken before falling back to process.env.LINEAR_API_TOKEN. The token needs to be passed through the LinearServiceConfig in IssueTrackerFactory, requiring minimal changes (approximately 40 LOC across 2 files). The MCP server flow already demonstrates the correct pattern (src/utils/mcp.ts:79-82). No breaking changes, no architectural concerns, and well-isolated modification scope.

[acreeger]

Combined Analysis & Plan - Issue #381

Executive Summary

Linear API token configured in settings.local.json is not being used by CLI commands. The getLinearApiToken() function in src/utils/linear.ts only checks process.env.LINEAR_API_TOKEN, ignoring the apiToken field from settings. The fix passes the token from settings through IssueTrackerFactory -> LinearService and sets it as an environment variable, following the established pattern from mcp.ts:79-82.

Implementation Overview

High-Level Execution Phases

1. Update LinearServiceConfig: Add optional apiToken field to the interface
2. Update IssueTrackerFactory: Pass apiToken from settings when creating LinearService
3. Update LinearService: Set process.env.LINEAR_API_TOKEN from config if provided
4. Add unit tests: Test token loading from config vs environment

Quick Stats

• 2 files to modify
• 0 new files to create
• 0 files to delete
• 1 test file to create
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: CLI commands like il a fail when Linear token is only in settings.local.json and not in environment
• Architectural context: Token should flow from settings -> factory -> service -> utilities
• Edge cases: Token in both settings and env (settings should take precedence per mcp.ts pattern)

Codebase Research

• Entry point: src/utils/linear.ts:64-73 - getLinearApiToken() only checks env var
• Working pattern: src/utils/mcp.ts:79-82 - reads from settings with env fallback and sets env var
• Settings schema: src/lib/SettingsManager.ts:318-321 - apiToken field exists in schema
• Factory: src/lib/IssueTrackerFactory.ts:39-51 - creates LinearService but doesn't pass apiToken

Affected Files

• /src/lib/LinearService.ts:21-26 - Add apiToken to config interface
• /src/lib/LinearService.ts:39-45 - Set env var in constructor
• /src/lib/IssueTrackerFactory.ts:43-48 - Pass apiToken to LinearService config

Integration Points

• IssueTrackerFactory.create() receives full settings including issueManagement.linear.apiToken
• LinearService constructor receives config and stores it
• Linear utility functions use process.env.LINEAR_API_TOKEN via getLinearApiToken()

---

Implementation Plan

Automated Test Cases to Create

Test File: /src/lib/LinearService.test.ts (NEW)

// Tests for LINEAR_API_TOKEN loading from config
describe('LinearService', () => {
  describe('constructor', () => {
    it('should set LINEAR_API_TOKEN env var when apiToken provided in config', () => {
      // Setup: clear env var, create service with apiToken config
      // Verify: process.env.LINEAR_API_TOKEN is set
    })

    it('should not override LINEAR_API_TOKEN if already set and no config token', () => {
      // Setup: set env var, create service without apiToken
      // Verify: original env var value preserved
    })
  })
})

Files to Modify

1. /src/lib/LinearService.ts:21-26

Change: Add apiToken to LinearServiceConfig interface

export interface LinearServiceConfig {
  /** Linear team key (e.g., "ENG", "PLAT") */
  teamId?: string
  /** Branch naming template (e.g., "feat/{{key}}__{{title}}") */
  branchFormat?: string
  /** Linear API token (lin_api_...). If provided, sets process.env.LINEAR_API_TOKEN */
  apiToken?: string
}

2. /src/lib/LinearService.ts:39-45

Change: In constructor, set process.env.LINEAR_API_TOKEN if apiToken is provided in config

Add after this.config = config ?? {} on line 43:

// Set API token from config if provided (follows mcp.ts pattern)
if (this.config.apiToken) {
  process.env.LINEAR_API_TOKEN = this.config.apiToken
}

3. /src/lib/IssueTrackerFactory.ts:43-48

Change: Pass apiToken from settings to LinearService config

Update the linear case (lines 39-51) to include apiToken:

if (linearSettings?.apiToken) {
  linearConfig.apiToken = linearSettings.apiToken
}

Detailed Execution Order

Phase 1: Update LinearService

1. Add apiToken?: string to LinearServiceConfig interface at line 26 -> Verify: TypeScript compiles
2. Add env var assignment in constructor after line 43 -> Verify: pnpm compile passes

Phase 2: Update IssueTrackerFactory

1. Add conditional apiToken assignment in linear case after line 48 -> Verify: pnpm compile passes

Phase 3: Create Tests

1. Create /src/lib/LinearService.test.ts with constructor tests -> Verify: pnpm test passes

Phase 4: Build and Verify

1. Run pnpm build -> Verify: Build succeeds
2. Manual test with settings.local.json containing Linear apiToken -> Verify: CLI reads token correctly

Dependencies and Configuration

None

[acreeger]

Implementation Complete - Issue #381

Summary

Linear API token from settings.local.json is now properly passed through to the LinearService. When configured in settings, the token is set as process.env.LINEAR_API_TOKEN so existing utility functions pick it up automatically.

Changes Made

• src/lib/LinearService.ts: Added apiToken to config interface and set env var in constructor
• src/lib/IssueTrackerFactory.ts: Pass apiToken from settings to LinearService config
• src/lib/LinearService.test.ts: Added tests for constructor token handling

Validation Results

• Tests: 3009 passed / 3032 total (23 skipped)
• Typecheck: Passed
• Lint: Passed
• Build: Passed

---

Detailed Changes by File (click to expand)

Files Modified

/src/lib/LinearService.ts

Changes: Added apiToken?: string to LinearServiceConfig interface and set process.env.LINEAR_API_TOKEN in constructor when token is provided in config.

/src/lib/IssueTrackerFactory.ts

Changes: Added conditional to pass apiToken from settings.issueManagement.linear.apiToken to LinearService config.

Files Created

/src/lib/LinearService.test.ts (NEW)

Purpose: Tests for LinearService constructor token handling - verifies env var is set when token provided, preserved when not, and properly overrides existing env var.

Test Coverage Added

• LinearService.test.ts: 5 tests covering constructor behavior for API token handling

Dependencies Added

None

[acreeger]

iloom Session Summary

Key Themes:

• Settings-based configuration should take precedence over environment variables for better user experience
• Setting environment variables in constructors allows existing utility functions to work without changes
• Comprehensive test coverage prevents regressions when modifying core authentication flows

---

Session Details (click to expand)

Key Insights

• The MCP server flow (src/utils/mcp.ts:79-82) already demonstrated the correct pattern for reading Linear API token from settings with environment variable fallback
• The getLinearApiToken() utility function in src/utils/linear.ts only checked process.env.LINEAR_API_TOKEN, making it incompatible with settings-based configuration
• Setting process.env.LINEAR_API_TOKEN in the LinearService constructor preserved the existing API without requiring changes to downstream utility functions
• The error message already suggested configuring in settings.local.json, but that path didn't actually work until this fix

Decisions Made

• Decision: Set process.env.LINEAR_API_TOKEN in the LinearService constructor when apiToken is provided in config
  • Rationale: This approach allowed the existing getLinearApiToken() utility function to work without modification, minimizing the scope of changes and maintaining backwards compatibility
• Decision: Add optional apiToken field to LinearServiceConfig interface
  • Rationale: Made the configuration explicit and type-safe, following the established pattern in other parts of the codebase
• Decision: Pass token through factory chain (Settings → IssueTrackerFactory → LinearService)
  • Rationale: Maintained separation of concerns and followed existing architectural patterns for dependency injection

Challenges Resolved

• Challenge: Needed to make settings-based token available to utility function that only checked environment variables
  • Resolution: Set the environment variable in the service constructor, allowing existing utility code to work unchanged
• Challenge: Ensuring the fix didn't break existing users who rely on LINEAR_API_TOKEN environment variable
  • Resolution: The environment variable is only set when apiToken is provided in config, preserving existing behavior for users who don't use settings

Lessons Learned

• When fixing configuration bugs, look for existing patterns in the codebase (like the MCP server flow) that demonstrate the intended behavior
• Setting environment variables early in the initialization chain can be an effective way to propagate configuration without refactoring large portions of code
• Comprehensive test coverage (5 tests covering token handling scenarios) helps ensure the fix works correctly and prevents future regressions
• The pattern of "settings with environment variable fallback" is common in the codebase and should be applied consistently across all service integrations

---

Generated with 🤖❤️ by iloom.ai