Add --mine support to il issues for github and Linear

[acreeger]

Fixes #605

---

This PR was created automatically by iloom.

[acreeger]

Enhancement Analysis

• Fetch issue details
• Read project documentation (CLAUDE.md, README.md, iloom-commands.md)
• Analyze requirements and identify gaps
• Produce structured enhancement specification

---

Enhancement Analysis

Questions for Reporter

Question	Answer
Should --mine also filter the PRs returned by il issues (e.g., only PRs authored by or assigned to the current user), or only filter the issues portion?	@acreeger Assumed: yes, --mine should filter both issues and PRs in the merged list, since showing unrelated PRs alongside filtered issues would be inconsistent.
For GitHub, should "mine" mean issues assigned to the current user, or also include issues created by the current user?	Assumed: assigned to the current user only, matching the Jira behavior which filters by assignee via currentUser().
For Linear, should "mine" mean issues assigned to the API token owner, consistent with the GitHub and Jira behavior?	Assumed: yes, assigned to the authenticated user (the API token owner), for consistency across all three providers.
The current docs say --sprint and --mine are "Jira only" and log a warning when used with other providers. After this change, should --mine silently work on all providers, or should the warning be removed only for --mine while --sprint remains Jira-only?	Assumed: remove the "Jira only" restriction for --mine so it works across all providers without warnings. --sprint remains Jira-only.

Problem Summary
The --mine flag on il issues currently only works with Jira. Users on GitHub and Linear projects cannot filter the issue list to show only their assigned work, forcing them to scan through all open issues to find their own tasks.

User Impact
Developers using GitHub or Linear as their issue tracker on teams with many open issues cannot quickly see only the issues assigned to them, reducing the usefulness of il issues and the VS Code extension's issue list for personal task management.

Enhancement Goal
Extend the existing --mine flag in il issues to work with all three supported issue providers (GitHub, Linear, and Jira) so users can filter the issue and PR list to show only items assigned to them, regardless of which issue tracker their project uses.

Next Steps

• Reporter to confirm or correct the assumptions in the questions table above
• Technical analysis to determine how each provider's API surfaces "assigned to current user" filtering
• Implementation planning and execution
• Documentation update to remove the "Jira only" annotation from --mine in docs/iloom-commands.md

---

Complete Context and Details (click to expand)

Current State

• il issues supports three issue providers: GitHub (via gh CLI), Linear (via @linear/sdk), and Jira (via REST API)
• The --mine flag exists today but is documented and implemented as "Jira only"
• When --mine is used with GitHub or Linear, a warning is logged and the flag is ignored
• Jira's --mine implementation uses the currentUser() JQL function to filter by the authenticated user
• il issues returns a merged, sorted list of both issues and PRs (PRs always come from GitHub)
• Results are cached on disk with a 2-minute TTL

Provider-Specific Context

• GitHub: Authentication is handled via gh auth login. The authenticated user identity is available through the gh CLI
• Linear: Authentication uses an API token stored in settings.local.json. The token implicitly identifies the user
• Jira: Authentication uses username + API token. The currentUser() JQL function provides the filter

Related Documentation

• The il issues command reference is in docs/iloom-commands.md under "Issue Management Commands"
• The README Acknowledgments section notes that Jira integration (PR feat: add Jira integration as issue tracker provider #588) already includes "sprint/mine filtering"
• The doneStatuses Jira config option controls which statuses are excluded from il issues output

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 5-6
• Estimated lines of code: 200-250
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good - utility modules are well-organized and <1000 LOC each
• Architectural signals triggered: None
• Overall risk level: Low

Reasoning: The --mine flag infrastructure already exists and is threaded through the command. Implementation follows the established Jira pattern: get authenticated user identity, then filter by assignee. Scope includes updating utility functions (issues.ts, github.ts, linear.ts), CLI help text (cli.ts), documentation (docs/iloom-commands.md), and tests. Key considerations: (1) when --mine is active with Linear/Jira backends, GitHub user identity must still be resolved to filter cross-provider PRs; (2) fetchGitHubPRList needs modification or PRs should be filtered post-fetch in issues.ts; (3) the existing "Jira only" warning must be split so --sprint warns but --mine does not. No cross-layer complexity or architectural decisions needed.

[acreeger]

Combined Analysis & Plan - Issue #605

Executive Summary

The --mine flag on il issues currently only works with Jira. This plan extends it to GitHub (using gh issue list --assignee @me and gh pr list --assignee @me) and Linear (using the SDK's assignee: { isMe: { eq: true } } filter). The existing warning guard in issues.ts must be split so --sprint remains Jira-only while --mine works for all providers.

Implementation Overview

High-Level Execution Phases

1. Utility layer: Add mine option to fetchGitHubIssueList, fetchGitHubPRList, and fetchLinearIssueList
2. Command layer: Update issues.ts to pass mine through to all providers and split the warning guard
3. CLI layer: Update cli.ts help text to remove "Jira only" from --mine
4. Documentation: Update docs/iloom-commands.md to reflect cross-provider support
5. Tests: Add test cases for --mine behavior across providers

Quick Stats

• 5 files to modify
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: --mine is Jira-only; GitHub/Linear users cannot filter to their assigned issues
• Architectural context: Each provider has its own fetch function in src/utils/; issues.ts orchestrates and merges results
• Edge cases: When issue tracker is Linear/Jira, PRs still come from GitHub and must also be filtered by --mine

Third-Party Research

• GitHub CLI: gh issue list --assignee @me and gh pr list --assignee @me are natively supported flags (Source: WebSearch)
• Linear SDK: team.issues() accepts filter: { assignee: { isMe: { eq: true } } } to filter by API token owner (Source: Context7/Linear docs)

Codebase Research

• Entry point: src/commands/issues.ts:134 - warning guard blocks --mine for non-Jira providers
• GitHub fetch: src/utils/github.ts:772-801 (fetchGitHubIssueList) and src/utils/github.ts:810-844 (fetchGitHubPRList) - neither accepts mine option
• Linear fetch: src/utils/linear.ts:721-776 (fetchLinearIssueList) - no mine option
• Jira fetch: src/utils/jira.ts:30-72 (fetchJiraIssueList) - already implements mine via currentUser() JQL
• CLI definition: src/cli.ts:1336 - --mine described as "Jira only"
• Tests: src/commands/issues.test.ts - existing test file covers all providers, no --mine tests yet

Affected Files

• src/utils/github.ts:772-844 - Add mine option to fetchGitHubIssueList and fetchGitHubPRList
• src/utils/linear.ts:721-776 - Add mine option to fetchLinearIssueList
• src/commands/issues.ts:134-210 - Split warning guard, pass mine to GitHub/Linear fetches and PR fetch
• src/cli.ts:1336 - Update help text
• docs/iloom-commands.md:1246,1285-1288 - Update documentation
• src/commands/issues.test.ts - Add test cases

Medium Severity Risks

• GitHub CLI @me requires auth: If gh is not authenticated, --assignee @me will fail - but this is already handled by the existing error catch block in issues.ts:212-229.

---

Implementation Plan

Automated Test Cases to Create

Test File: src/commands/issues.test.ts (MODIFY)

Click to expand complete test structure (25 lines)

describe('execute - --mine flag', () => {
  // GitHub provider
  it('passes mine option to fetchGitHubIssueList when provider is github', async () => {
    // Setup github provider, call with mine: true
    // Verify fetchGitHubIssueList called with { mine: true, ... }
  })

  it('passes mine option to fetchGitHubPRList when --mine is active', async () => {
    // Verify fetchGitHubPRList called with { mine: true, ... }
  })

  // Linear provider
  it('passes mine option to fetchLinearIssueList when provider is linear', async () => {
    // Setup linear provider, call with mine: true
    // Verify fetchLinearIssueList called with { mine: true, ... }
  })

  it('passes mine option to fetchGitHubPRList when provider is linear and --mine is active', async () => {
    // Verify cross-provider PR filtering
  })

  // Warning guard split
  it('does not warn when --mine used with github provider', async () => {
    // Verify no logger.warn call
  })

  it('warns only for --sprint with non-jira provider, not --mine', async () => {
    // Use --sprint with github, verify warning only mentions --sprint
  })
})

Files to Modify

1. src/utils/github.ts:772-801

Change: Add optional mine param to fetchGitHubIssueList; when truthy, add '--assignee', '@me' to the gh issue list args array.

2. src/utils/github.ts:810-844

Change: Add optional mine param to fetchGitHubPRList; when truthy, add '--assignee', '@me' to the gh pr list args array.

3. src/utils/linear.ts:721-776

Change: Add optional mine param to fetchLinearIssueList options; when truthy, add assignee: { isMe: { eq: true } } to the existing filter object passed to team.issues().

4. src/commands/issues.ts:134-136

Change: Split the warning guard. Replace the combined (sprint || mine) check with separate checks: warn only for sprint with non-Jira provider. Remove the mine restriction entirely so it flows through to all providers.
Cross-cutting impact: The mine option already exists in IssuesCommandOptions and is already threaded through to the Jira path. Now it must also be forwarded to the GitHub and Linear fetch calls.

5. src/commands/issues.ts:150-155

Change: Pass mine to fetchGitHubIssueList call: { limit, cwd: resolvedProjectPath, mine }.

6. src/commands/issues.ts:163-166

Change: Pass mine to fetchLinearIssueList call: add ...(mine ? { mine } : {}) to options.

7. src/commands/issues.ts:206-209

Change: Pass mine to fetchGitHubPRList call: { limit, cwd: resolvedProjectPath, mine }.

8. src/cli.ts:1336

Change: Update option description from 'Jira only: show only issues assigned to me' to 'Show only issues and PRs assigned to me'.

9. docs/iloom-commands.md:1246

Change: Update --mine row: remove "Jira only" prefix, change description to "Show only issues and PRs assigned to the authenticated user".

10. docs/iloom-commands.md:1285-1288

Change: Update behavior notes: --sprint remains Jira-only; --mine works across all providers. Remove the "Jira only" language for --mine. Add notes about how each provider implements the filter (GitHub: --assignee @me, Linear: SDK assignee filter, Jira: currentUser() JQL).

11. docs/iloom-commands.md:1315-1319

Change: Update examples section: remove "Jira:" prefix from --mine examples, add GitHub and Linear examples.

12. src/commands/issues.test.ts

Change: Add test cases as described in the test plan above.

Detailed Execution Order

NOTE: These steps are executed in a SINGLE implementation run.

1. Add mine param to fetchGitHubIssueList

   • Files: src/utils/github.ts
   • Add mine?: boolean to options type, add --assignee @me args when truthy -> Verify: TypeScript compiles

2. Add mine param to fetchGitHubPRList

   • Files: src/utils/github.ts
   • Add mine?: boolean to options type, add --assignee @me args when truthy -> Verify: TypeScript compiles

3. Add mine param to fetchLinearIssueList

   • Files: src/utils/linear.ts
   • Add mine?: boolean to options type, add assignee: { isMe: { eq: true } } to filter when truthy -> Verify: TypeScript compiles

4. Split warning guard and pass mine through in issues.ts

   • Files: src/commands/issues.ts
   • Split the (sprint || mine) warning to only warn for sprint on non-Jira
   • Pass mine to fetchGitHubIssueList, fetchLinearIssueList, and fetchGitHubPRList -> Verify: TypeScript compiles

5. Update CLI help text

   • Files: src/cli.ts
   • Change --mine description -> Verify: il issues --help shows updated text

6. Update documentation

   • Files: docs/iloom-commands.md
   • Update flag table, behavior notes, and examples -> Verify: docs are consistent

7. Add tests

   • Files: src/commands/issues.test.ts
   • Add --mine test cases for GitHub, Linear, PR cross-filtering, and warning guard split -> Verify: pnpm test src/commands/issues.test.ts passes

8. Build

   • Run pnpm build -> Verify: clean compilation

Dependencies and Configuration

None

[acreeger]

Implementation Complete

Summary

Extended the --mine flag on il issues from Jira-only to all three providers (GitHub, Linear, Jira). GitHub uses --assignee @me for both issues and PRs, Linear uses the SDK's assignee: { isMe: { eq: true } } filter. The warning guard was split so --sprint remains Jira-only while --mine works cross-provider.

Changes Made

• src/utils/github.ts: Added mine option to fetchGitHubIssueList and fetchGitHubPRList - appends --assignee @me to gh CLI args
• src/utils/linear.ts: Added mine option to fetchLinearIssueList - adds assignee isMe filter to SDK query
• src/commands/issues.ts: Split warning guard (sprint-only), pass mine to all fetch calls including cross-provider PR fetch
• src/cli.ts: Updated --mine help text to remove "Jira only"
• docs/iloom-commands.md: Updated flag table, behavior notes, and examples for cross-provider --mine support
• src/commands/issues.test.ts: Added 8 new tests covering --mine for GitHub, Linear, PR cross-filtering, and warning guard split

Validation Results

• Tests: 33 passed / 33 total
• Typecheck: Passed
• Lint: Passed
• Build: Passed

[acreeger]

iloom Session Summary

Key Themes:

• Extended --mine flag from Jira-only to all three providers (GitHub, Linear, Jira) using native API-level filtering
• Stale cache entries can mask implementation bugs - cache keys must include all filter parameters
• Cross-provider PR filtering requires GitHub user resolution even when using non-GitHub issue trackers

---

Session Details (click to expand)

Key Insights

• The --mine flag infrastructure already existed for Jira but was blocked by a warning guard that prevented it from working with GitHub/Linear providers
• GitHub CLI natively supports --assignee @me for both issues and PRs, eliminating the need to resolve usernames
• Linear SDK provides assignee: { isMe: { eq: true } } filter syntax for authenticated user filtering (verified against installed SDK types at node_modules/@linear/sdk/dist/_generated_documents.d.ts)
• The warning guard at issues.ts:134 only logs a warning and continues execution - the actual issue was that the mine parameter wasn't being passed to the GitHub/Linear fetch functions
• PRs are always fetched from GitHub regardless of which issue tracker is configured, so mine must be passed to fetchGitHubPRList even when the primary provider is Linear or Jira
• Cache keys in getCacheFilePath() already included the mine flag in the hash computation, preventing cache pollution between filtered and unfiltered queries

Decisions Made

• Split warning guard logic: --sprint remains Jira-only (logs warning for non-Jira providers), but --mine now works across all providers without warnings
• Use native API filtering: Each provider uses its own native filter mechanism (--assignee @me for GitHub, assignee.isMe.eq: true for Linear, currentUser() JQL for Jira) rather than fetching all results and filtering client-side
• Apply mine filter to PRs: When --mine is active, both issues AND PRs are filtered to show only items assigned to/authored by the current user, since il issues returns a merged list

Challenges Resolved

• Empty results despite correct implementation: Initial testing returned [] even though the code was correct. The issue was a stale cache entry from before the flag was wired up. The cache file at ~/.config/iloom-ai/cache/issues-006abf293cbe.json contained an empty result from when the flag was ignored. Deleting the cache file revealed the implementation was working correctly.
• Cross-provider complexity underestimated: Initial complexity evaluation claimed "3 files affected" but actually needed 6 files (CLI help text, documentation, tests were overlooked). The cross-provider PR filtering concern was also initially missed - when using Linear/Jira as issue tracker, GitHub user identity must still be resolved to filter PRs.

Lessons Learned

• Cache invalidation bugs are particularly insidious during feature development - testing new flags can return stale empty results that mask working implementations
• The il issues command is designed for programmatic consumption by the VS Code extension, not just CLI usage - the --mine filter reduces noise in team contexts where users only want to see their assigned work
• When a flag affects merged results from multiple providers (issues + PRs), the filter must be applied consistently to all data sources, not just the primary issue tracker
• The Linear SDK's type system is complex and not fully exported, which is why the filter construction uses any type with an eslint-disable comment - attempting to type it strictly would be brittle

---

Generated with 🤖❤️ by iloom.ai