prjct-cli 0.40.0 → 0.41.0

package/core/integrations/jira/cache.ts

@@ -0,0 +1,57 @@
+/**
+ * JIRA Cache Module
+ * 5-minute TTL cache for JIRA API responses to reduce API calls
+ */
+
+import { TTLCache } from '../../utils/cache'
+import type { Issue } from '../issue-tracker/types'
+
+// 5-minute TTL for JIRA API responses
+const JIRA_CACHE_TTL = 5 * 60 * 1000 // 300000ms
+
+/**
+ * Cache for individual issues (by key like "ENG-123" or ID)
+ * Key format: "issue:{key}" or "issue:{id}"
+ */
+export const issueCache = new TTLCache<Issue>({
+  ttl: JIRA_CACHE_TTL,
+  maxSize: 100,
+})
+
+/**
+ * Cache for assigned issues list
+ * Key format: "assigned:{userId}" or "assigned:me"
+ */
+export const assignedIssuesCache = new TTLCache<Issue[]>({
+  ttl: JIRA_CACHE_TTL,
+  maxSize: 10,
+})
+
+/**
+ * Cache for projects list
+ * Key format: "projects"
+ */
+export const projectsCache = new TTLCache<Array<{ id: string; name: string; key?: string }>>({
+  ttl: JIRA_CACHE_TTL,
+  maxSize: 5,
+})
+
+/**
+ * Clear all JIRA caches
+ */
+export function clearJiraCache(): void {
+  issueCache.clear()
+  assignedIssuesCache.clear()
+  projectsCache.clear()
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getJiraCacheStats() {
+  return {
+    issues: issueCache.stats(),
+    assignedIssues: assignedIssuesCache.stats(),
+    projects: projectsCache.stats(),
+  }
+}

package/core/integrations/jira/index.ts

@@ -1,25 +1,30 @@
 /**
  * JIRA Integration
  *
- * Provides JIRA issue tracking integration for prjct-cli.
+ * Provides JIRA issue tracking integration for prjct-cli using REST API.
  *
- * Two authentication modes:
- *
- * 1. API Token Mode (direct REST API):
+ * Authentication (API Token Mode):
  *    - JIRA_BASE_URL: Your JIRA instance URL (e.g., https://company.atlassian.net)
  *    - JIRA_EMAIL: Your Atlassian account email
  *    - JIRA_API_TOKEN: API token from https://id.atlassian.com/manage-profile/security/api-tokens
- *
- * 2. MCP Mode (for corporate SSO):
- *    - No environment variables needed
- *    - Requires Atlassian MCP server configured in ~/.claude/mcp.json
- *    - Authenticates via browser (OAuth 2.1, SSO compatible)
  */
 
-// REST API client (supports both API token and MCP modes)
+// REST API client
 export { JiraProvider, jiraProvider, type JiraAuthMode } from './client'
 
-// MCP adapter for generating Claude instructions
+// Service layer with caching (preferred API)
+export { JiraService, jiraService } from './service'
+
+// Cache utilities
+export {
+  issueCache,
+  assignedIssuesCache,
+  projectsCache,
+  clearJiraCache,
+  getJiraCacheStats,
+} from './cache'
+
+// MCP adapter (deprecated - will be removed)
 export {
   JiraMCPAdapter,
   jiraMCPAdapter,

package/core/integrations/jira/service.ts

@@ -0,0 +1,244 @@
+/**
+ * JIRA Service Layer
+ * Wraps JiraProvider with caching for improved performance.
+ * All operations are cached with 5-minute TTL.
+ */
+
+import { jiraProvider } from './client'
+import {
+  issueCache,
+  assignedIssuesCache,
+  projectsCache,
+  clearJiraCache,
+  getJiraCacheStats,
+} from './cache'
+import type {
+  Issue,
+  CreateIssueInput,
+  UpdateIssueInput,
+  FetchOptions,
+  JiraConfig,
+} from '../issue-tracker/types'
+
+export class JiraService {
+  private initialized = false
+  private userId: string | null = null
+
+  /**
+   * Check if service is ready
+   */
+  isReady(): boolean {
+    return this.initialized && jiraProvider.isConfigured()
+  }
+
+  /**
+   * Initialize the service with config
+   * Must be called before any operations
+   */
+  async initialize(config: JiraConfig): Promise<void> {
+    if (this.initialized) return
+
+    await jiraProvider.initialize(config)
+    this.initialized = true
+  }
+
+  /**
+   * Initialize from credentials directly
+   * Convenience method for simple setup
+   */
+  async initializeFromCredentials(
+    baseUrl: string,
+    email: string,
+    apiToken: string,
+    projectKey?: string
+  ): Promise<void> {
+    // Set env vars for the provider
+    process.env.JIRA_BASE_URL = baseUrl
+    process.env.JIRA_EMAIL = email
+    process.env.JIRA_API_TOKEN = apiToken
+
+    const config: JiraConfig = {
+      enabled: true,
+      provider: 'jira',
+      baseUrl,
+      projectKey,
+      syncOn: { task: true, done: true, ship: true },
+      enrichment: { enabled: true, updateProvider: true },
+    }
+    await this.initialize(config)
+  }
+
+  /**
+   * Get issues assigned to current user (cached)
+   */
+  async fetchAssignedIssues(options?: FetchOptions): Promise<Issue[]> {
+    this.ensureInitialized()
+
+    const cacheKey = `assigned:${this.userId || 'me'}`
+    const cached = assignedIssuesCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issues = await jiraProvider.fetchAssignedIssues(options)
+    assignedIssuesCache.set(cacheKey, issues)
+
+    // Also cache individual issues
+    for (const issue of issues) {
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issues
+  }
+
+  /**
+   * Get issues from a project (cached)
+   */
+  async fetchProjectIssues(projectKey: string, options?: FetchOptions): Promise<Issue[]> {
+    this.ensureInitialized()
+
+    const cacheKey = `project:${projectKey}`
+    const cached = assignedIssuesCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issues = await jiraProvider.fetchTeamIssues(projectKey, options)
+    assignedIssuesCache.set(cacheKey, issues)
+
+    // Also cache individual issues
+    for (const issue of issues) {
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issues
+  }
+
+  /**
+   * Get a single issue by key (like "ENG-123") or ID (cached)
+   */
+  async fetchIssue(id: string): Promise<Issue | null> {
+    this.ensureInitialized()
+
+    // Check cache first
+    const cacheKey = `issue:${id}`
+    const cached = issueCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issue = await jiraProvider.fetchIssue(id)
+    if (issue) {
+      // Cache by both ID and key
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issue
+  }
+
+  /**
+   * Create a new issue (invalidates assigned cache)
+   */
+  async createIssue(input: CreateIssueInput): Promise<Issue> {
+    this.ensureInitialized()
+
+    const issue = await jiraProvider.createIssue(input)
+
+    // Cache the new issue
+    issueCache.set(`issue:${issue.id}`, issue)
+    issueCache.set(`issue:${issue.externalId}`, issue)
+
+    // Invalidate assigned issues cache (new issue may be assigned)
+    assignedIssuesCache.clear()
+
+    return issue
+  }
+
+  /**
+   * Update an issue (invalidates cache for that issue)
+   */
+  async updateIssue(id: string, input: UpdateIssueInput): Promise<Issue> {
+    this.ensureInitialized()
+
+    const issue = await jiraProvider.updateIssue(id, input)
+
+    // Update cache
+    issueCache.set(`issue:${issue.id}`, issue)
+    issueCache.set(`issue:${issue.externalId}`, issue)
+
+    return issue
+  }
+
+  /**
+   * Mark issue as in progress (invalidates cache)
+   */
+  async markInProgress(id: string): Promise<void> {
+    this.ensureInitialized()
+
+    await jiraProvider.markInProgress(id)
+
+    // Invalidate caches
+    issueCache.delete(`issue:${id}`)
+    assignedIssuesCache.clear()
+  }
+
+  /**
+   * Mark issue as done (invalidates cache)
+   */
+  async markDone(id: string): Promise<void> {
+    this.ensureInitialized()
+
+    await jiraProvider.markDone(id)
+
+    // Invalidate caches
+    issueCache.delete(`issue:${id}`)
+    assignedIssuesCache.clear()
+  }
+
+  /**
+   * Get available projects (cached)
+   */
+  async getProjects(): Promise<Array<{ id: string; name: string; key?: string }>> {
+    this.ensureInitialized()
+
+    const cached = projectsCache.get('projects')
+    if (cached) {
+      return cached
+    }
+
+    const projects = await jiraProvider.getTeams()
+    projectsCache.set('projects', projects)
+    return projects
+  }
+
+  /**
+   * Clear all caches
+   */
+  clearCache(): void {
+    clearJiraCache()
+  }
+
+  /**
+   * Get cache statistics for debugging
+   */
+  getCacheStats() {
+    return getJiraCacheStats()
+  }
+
+  /**
+   * Ensure service is initialized
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error(
+        'JIRA service not initialized. Call jiraService.initialize() first or run `p. jira setup`.'
+      )
+    }
+  }
+}
+
+// Singleton instance
+export const jiraService = new JiraService()

package/core/integrations/linear/cache.ts

@@ -0,0 +1,68 @@
+/**
+ * Linear Cache Module
+ * 5-minute TTL cache for Linear API responses to reduce API calls
+ */
+
+import { TTLCache } from '../../utils/cache'
+import type { Issue } from '../issue-tracker/types'
+
+// 5-minute TTL for Linear API responses
+const LINEAR_CACHE_TTL = 5 * 60 * 1000 // 300000ms
+
+/**
+ * Cache for individual issues (by ID or identifier)
+ * Key format: "issue:{id}" or "issue:{identifier}"
+ */
+export const issueCache = new TTLCache<Issue>({
+  ttl: LINEAR_CACHE_TTL,
+  maxSize: 100,
+})
+
+/**
+ * Cache for assigned issues list
+ * Key format: "assigned:{userId}" or "assigned:me"
+ */
+export const assignedIssuesCache = new TTLCache<Issue[]>({
+  ttl: LINEAR_CACHE_TTL,
+  maxSize: 10,
+})
+
+/**
+ * Cache for teams list
+ * Key format: "teams"
+ */
+export const teamsCache = new TTLCache<Array<{ id: string; name: string; key?: string }>>({
+  ttl: LINEAR_CACHE_TTL,
+  maxSize: 5,
+})
+
+/**
+ * Cache for projects list
+ * Key format: "projects"
+ */
+export const projectsCache = new TTLCache<Array<{ id: string; name: string }>>({
+  ttl: LINEAR_CACHE_TTL,
+  maxSize: 5,
+})
+
+/**
+ * Clear all Linear caches
+ */
+export function clearLinearCache(): void {
+  issueCache.clear()
+  assignedIssuesCache.clear()
+  teamsCache.clear()
+  projectsCache.clear()
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getLinearCacheStats() {
+  return {
+    issues: issueCache.stats(),
+    assignedIssues: assignedIssuesCache.stats(),
+    teams: teamsCache.stats(),
+    projects: projectsCache.stats(),
+  }
+}

package/core/integrations/linear/index.ts

@@ -1,6 +1,20 @@
 /**
  * Linear Integration
- * Issue tracker provider for Linear.
+ * Issue tracker provider for Linear using @linear/sdk
  */
 
+// Core provider
 export { LinearProvider, linearProvider } from './client'
+
+// Service layer with caching (preferred API)
+export { LinearService, linearService } from './service'
+
+// Cache utilities
+export {
+  issueCache,
+  assignedIssuesCache,
+  teamsCache,
+  projectsCache,
+  clearLinearCache,
+  getLinearCacheStats,
+} from './cache'

package/core/integrations/linear/service.ts

@@ -0,0 +1,260 @@
+/**
+ * Linear Service Layer
+ * Wraps LinearProvider with caching for improved performance.
+ * All operations are cached with 5-minute TTL.
+ */
+
+import { linearProvider } from './client'
+import {
+  issueCache,
+  assignedIssuesCache,
+  teamsCache,
+  projectsCache,
+  clearLinearCache,
+  getLinearCacheStats,
+} from './cache'
+import type {
+  Issue,
+  CreateIssueInput,
+  UpdateIssueInput,
+  FetchOptions,
+  LinearConfig,
+} from '../issue-tracker/types'
+
+export class LinearService {
+  private initialized = false
+  private userId: string | null = null
+
+  /**
+   * Check if service is ready
+   */
+  isReady(): boolean {
+    return this.initialized && linearProvider.isConfigured()
+  }
+
+  /**
+   * Initialize the service with config
+   * Must be called before any operations
+   */
+  async initialize(config: LinearConfig): Promise<void> {
+    if (this.initialized) return
+
+    await linearProvider.initialize(config)
+    this.initialized = true
+  }
+
+  /**
+   * Initialize from API key directly
+   * Convenience method for simple setup
+   */
+  async initializeFromApiKey(apiKey: string, teamId?: string): Promise<void> {
+    const config: LinearConfig = {
+      enabled: true,
+      provider: 'linear',
+      apiKey,
+      defaultTeamId: teamId,
+      syncOn: { task: true, done: true, ship: true },
+      enrichment: { enabled: true, updateProvider: true },
+    }
+    await this.initialize(config)
+  }
+
+  /**
+   * Get issues assigned to current user (cached)
+   */
+  async fetchAssignedIssues(options?: FetchOptions): Promise<Issue[]> {
+    this.ensureInitialized()
+
+    const cacheKey = `assigned:${this.userId || 'me'}`
+    const cached = assignedIssuesCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issues = await linearProvider.fetchAssignedIssues(options)
+    assignedIssuesCache.set(cacheKey, issues)
+
+    // Also cache individual issues
+    for (const issue of issues) {
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issues
+  }
+
+  /**
+   * Get issues from a team (cached)
+   */
+  async fetchTeamIssues(teamId: string, options?: FetchOptions): Promise<Issue[]> {
+    this.ensureInitialized()
+
+    const cacheKey = `team:${teamId}`
+    const cached = assignedIssuesCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issues = await linearProvider.fetchTeamIssues(teamId, options)
+    assignedIssuesCache.set(cacheKey, issues)
+
+    // Also cache individual issues
+    for (const issue of issues) {
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issues
+  }
+
+  /**
+   * Get a single issue by ID or identifier (cached)
+   * Accepts UUID or identifier like "PRJ-123"
+   */
+  async fetchIssue(id: string): Promise<Issue | null> {
+    this.ensureInitialized()
+
+    // Check cache first
+    const cacheKey = `issue:${id}`
+    const cached = issueCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issue = await linearProvider.fetchIssue(id)
+    if (issue) {
+      // Cache by both ID and externalId
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issue
+  }
+
+  /**
+   * Create a new issue (invalidates assigned cache)
+   */
+  async createIssue(input: CreateIssueInput): Promise<Issue> {
+    this.ensureInitialized()
+
+    const issue = await linearProvider.createIssue(input)
+
+    // Cache the new issue
+    issueCache.set(`issue:${issue.id}`, issue)
+    issueCache.set(`issue:${issue.externalId}`, issue)
+
+    // Invalidate assigned issues cache (new issue may be assigned)
+    assignedIssuesCache.clear()
+
+    return issue
+  }
+
+  /**
+   * Update an issue (invalidates cache for that issue)
+   */
+  async updateIssue(id: string, input: UpdateIssueInput): Promise<Issue> {
+    this.ensureInitialized()
+
+    const issue = await linearProvider.updateIssue(id, input)
+
+    // Update cache
+    issueCache.set(`issue:${issue.id}`, issue)
+    issueCache.set(`issue:${issue.externalId}`, issue)
+
+    return issue
+  }
+
+  /**
+   * Mark issue as in progress (invalidates cache)
+   */
+  async markInProgress(id: string): Promise<void> {
+    this.ensureInitialized()
+
+    await linearProvider.markInProgress(id)
+
+    // Invalidate caches
+    issueCache.delete(`issue:${id}`)
+    assignedIssuesCache.clear()
+  }
+
+  /**
+   * Mark issue as done (invalidates cache)
+   */
+  async markDone(id: string): Promise<void> {
+    this.ensureInitialized()
+
+    await linearProvider.markDone(id)
+
+    // Invalidate caches
+    issueCache.delete(`issue:${id}`)
+    assignedIssuesCache.clear()
+  }
+
+  /**
+   * Add a comment to an issue
+   */
+  async addComment(id: string, body: string): Promise<void> {
+    this.ensureInitialized()
+    await linearProvider.addComment(id, body)
+  }
+
+  /**
+   * Get available teams (cached)
+   */
+  async getTeams(): Promise<Array<{ id: string; name: string; key?: string }>> {
+    this.ensureInitialized()
+
+    const cached = teamsCache.get('teams')
+    if (cached) {
+      return cached
+    }
+
+    const teams = await linearProvider.getTeams()
+    teamsCache.set('teams', teams)
+    return teams
+  }
+
+  /**
+   * Get available projects (cached)
+   */
+  async getProjects(): Promise<Array<{ id: string; name: string }>> {
+    this.ensureInitialized()
+
+    const cached = projectsCache.get('projects')
+    if (cached) {
+      return cached
+    }
+
+    const projects = await linearProvider.getProjects()
+    projectsCache.set('projects', projects)
+    return projects
+  }
+
+  /**
+   * Clear all caches
+   */
+  clearCache(): void {
+    clearLinearCache()
+  }
+
+  /**
+   * Get cache statistics for debugging
+   */
+  getCacheStats() {
+    return getLinearCacheStats()
+  }
+
+  /**
+   * Ensure service is initialized
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error(
+        'Linear service not initialized. Call linearService.initialize() first or run `p. linear setup`.'
+      )
+    }
+  }
+}
+
+// Singleton instance
+export const linearService = new LinearService()