memory-journal-mcp 4.3.0 → 4.4.0

package/dist/github/GitHubIntegration.js

@@ -8,6 +8,10 @@ import { Octokit } from '@octokit/rest';
 import { graphql } from '@octokit/graphql';
 import * as simpleGitImport from 'simple-git';
 import { logger } from '../utils/logger.js';
+/** TTL for cached GitHub API responses (5 minutes) */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+/** TTL for cached traffic/insights responses (10 minutes - traffic data changes slowly) */
+const TRAFFIC_CACHE_TTL_MS = 10 * 60 * 1000;
 const simpleGit = simpleGitImport.simpleGit;
 /**
  * GitHubIntegration - Handles GitHub API and local git operations
@@ -18,6 +22,8 @@ export class GitHubIntegration {
     git;
     token;
     cachedRepoInfo = null;
+    /** TTL response cache for GitHub API read methods */
+    apiCache = new Map();
     constructor(workingDir = '.') {
         this.token = process.env['GITHUB_TOKEN'];
         // Use GITHUB_REPO_PATH env var if set, otherwise fall back to workingDir
@@ -54,6 +60,43 @@ export class GitHubIntegration {
     isApiAvailable() {
         return this.octokit !== null;
     }
+    /**
+     * Get a cached value if it exists and hasn't expired.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- T is needed at call sites for type-safe casts
+    getCached(key) {
+        const entry = this.apiCache.get(key);
+        if (entry && Date.now() - entry.timestamp < CACHE_TTL_MS) {
+            return entry.data;
+        }
+        if (entry) {
+            this.apiCache.delete(key);
+        }
+        return undefined;
+    }
+    /**
+     * Store a value in the cache.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- T preserves type inference at call sites
+    setCache(key, data) {
+        this.apiCache.set(key, { data, timestamp: Date.now() });
+    }
+    /**
+     * Invalidate all cache entries matching a prefix.
+     */
+    invalidateCache(prefix) {
+        for (const key of this.apiCache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.apiCache.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear all cached GitHub API responses.
+     */
+    clearCache() {
+        this.apiCache.clear();
+    }
     /**
      * Get local repository information
      * Caches the result for synchronous access via getCachedRepoInfo()
@@ -127,6 +170,10 @@ export class GitHubIntegration {
         if (!this.octokit) {
             return [];
         }
+        const cacheKey = `issues:${owner}:${repo}:${state}:${String(limit)}`;
+        const cached = this.getCached(cacheKey);
+        if (cached)
+            return cached;
         try {
             const response = await this.octokit.issues.listForRepo({
                 owner,
@@ -137,14 +184,22 @@ export class GitHubIntegration {
                 direction: 'desc',
             });
             // Filter out pull requests (GitHub API includes PRs in issues)
-            return response.data
+            const result = response.data
                 .filter((issue) => !issue.pull_request)
                 .map((issue) => ({
                 number: issue.number,
                 title: issue.title,
                 url: issue.html_url,
                 state: issue.state === 'open' ? 'OPEN' : 'CLOSED',
+                milestone: issue.milestone
+                    ? {
+                        number: issue.milestone.number,
+                        title: issue.milestone.title,
+                    }
+                    : null,
             }));
+            this.setCache(cacheKey, result);
+            return result;
         }
         catch (error) {
             logger.error('Failed to get issues', {
@@ -161,6 +216,10 @@ export class GitHubIntegration {
         if (!this.octokit) {
             return null;
         }
+        const cacheKey = `issue:${owner}:${repo}:${String(issueNumber)}`;
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined)
+            return cached;
         try {
             const response = await this.octokit.issues.get({
                 owner,
@@ -172,7 +231,7 @@ export class GitHubIntegration {
             if (issue.pull_request) {
                 return null;
             }
-            return {
+            const details = {
                 number: issue.number,
                 title: issue.title,
                 url: issue.html_url,
@@ -184,7 +243,12 @@ export class GitHubIntegration {
                 updatedAt: issue.updated_at,
                 closedAt: issue.closed_at,
                 commentsCount: issue.comments,
+                milestone: issue.milestone
+                    ? { number: issue.milestone.number, title: issue.milestone.title }
+                    : null,
             };
+            this.setCache(cacheKey, details);
+            return details;
         }
         catch (error) {
             logger.error('Failed to get issue details', {
@@ -198,7 +262,7 @@ export class GitHubIntegration {
     /**
      * Create a new GitHub issue
      */
-    async createIssue(owner, repo, title, body, labels, assignees) {
+    async createIssue(owner, repo, title, body, labels, assignees, milestone) {
         if (!this.octokit) {
             logger.error('Cannot create issue: GitHub API not available', { module: 'GitHub' });
             return null;
@@ -211,6 +275,7 @@ export class GitHubIntegration {
                 body,
                 labels,
                 assignees,
+                milestone,
             });
             logger.info('Created GitHub issue', {
                 module: 'GitHub',
@@ -232,6 +297,10 @@ export class GitHubIntegration {
             });
             return null;
         }
+        finally {
+            this.invalidateCache(`issues:${owner}:${repo}`);
+            this.invalidateCache('context:');
+        }
     }
     /**
      * Close a GitHub issue with optional comment
@@ -276,6 +345,11 @@ export class GitHubIntegration {
             });
             return null;
         }
+        finally {
+            this.invalidateCache(`issues:${owner}:${repo}`);
+            this.invalidateCache(`issue:${owner}:${repo}:${String(issueNumber)}`);
+            this.invalidateCache('context:');
+        }
     }
     /**
      * Get repository pull requests
@@ -284,6 +358,10 @@ export class GitHubIntegration {
         if (!this.octokit) {
             return [];
         }
+        const cacheKey = `prs:${owner}:${repo}:${state}:${String(limit)}`;
+        const cached = this.getCached(cacheKey);
+        if (cached)
+            return cached;
         try {
             const response = await this.octokit.pulls.list({
                 owner,
@@ -293,12 +371,18 @@ export class GitHubIntegration {
                 sort: 'updated',
                 direction: 'desc',
             });
-            return response.data.map((pr) => ({
+            const result = response.data.map((pr) => ({
                 number: pr.number,
                 title: pr.title,
                 url: pr.html_url,
-                state: pr.merged_at ? 'MERGED' : pr.state === 'open' ? 'OPEN' : 'CLOSED',
+                state: pr.merged_at
+                    ? 'MERGED'
+                    : pr.state === 'open'
+                        ? 'OPEN'
+                        : 'CLOSED',
             }));
+            this.setCache(cacheKey, result);
+            return result;
         }
         catch (error) {
             logger.error('Failed to get pull requests', {
@@ -315,6 +399,10 @@ export class GitHubIntegration {
         if (!this.octokit) {
             return null;
         }
+        const cacheKey = `pr:${owner}:${repo}:${String(prNumber)}`;
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined)
+            return cached;
         try {
             const response = await this.octokit.pulls.get({
                 owner,
@@ -322,7 +410,7 @@ export class GitHubIntegration {
                 pull_number: prNumber,
             });
             const pr = response.data;
-            return {
+            const details = {
                 number: pr.number,
                 title: pr.title,
                 url: pr.html_url,
@@ -340,6 +428,8 @@ export class GitHubIntegration {
                 deletions: pr.deletions,
                 changedFiles: pr.changed_files,
             };
+            this.setCache(cacheKey, details);
+            return details;
         }
         catch (error) {
             logger.error('Failed to get PR details', {
@@ -358,13 +448,17 @@ export class GitHubIntegration {
             logger.debug('GitHub API not available - no token', { module: 'GitHub' });
             return [];
         }
+        const cacheKey = `workflows:${owner}:${repo}:${String(limit)}`;
+        const cached = this.getCached(cacheKey);
+        if (cached)
+            return cached;
         try {
             const response = await this.octokit.rest.actions.listWorkflowRunsForRepo({
                 owner,
                 repo,
                 per_page: limit,
             });
-            return response.data.workflow_runs.map((run) => ({
+            const result = response.data.workflow_runs.map((run) => ({
                 id: run.id,
                 name: run.name ?? 'Unknown Workflow',
                 status: run.status,
@@ -375,6 +469,8 @@ export class GitHubIntegration {
                 createdAt: run.created_at,
                 updatedAt: run.updated_at,
             }));
+            this.setCache(cacheKey, result);
+            return result;
         }
         catch (error) {
             logger.error('Failed to get workflow runs', {
@@ -388,6 +484,9 @@ export class GitHubIntegration {
      * Get full repository context (issues, PRs, branch info)
      */
     async getRepoContext() {
+        const cached = this.getCached('context:repo');
+        if (cached)
+            return cached;
         const repoInfo = await this.getRepoInfo();
         const context = {
             repoName: repoInfo.repo,
@@ -398,6 +497,7 @@ export class GitHubIntegration {
             issues: [],
             pullRequests: [],
             workflowRuns: [],
+            milestones: [],
         };
         // Get current commit
         try {
@@ -412,7 +512,9 @@ export class GitHubIntegration {
             context.issues = await this.getIssues(repoInfo.owner, repoInfo.repo, 'open', 10);
             context.pullRequests = await this.getPullRequests(repoInfo.owner, repoInfo.repo, 'open', 10);
             context.workflowRuns = await this.getWorkflowRuns(repoInfo.owner, repoInfo.repo, 10);
+            context.milestones = await this.getMilestones(repoInfo.owner, repoInfo.repo, 'open', 10);
         }
+        this.setCache('context:repo', context);
         return context;
     }
     // ==========================================================================
@@ -712,6 +814,9 @@ export class GitHubIntegration {
             });
             return { success: false, error: errorMessage };
         }
+        finally {
+            this.invalidateCache('kanban:');
+        }
     }
     /**
      * Add an item to a GitHub Project v2
@@ -750,6 +855,402 @@ export class GitHubIntegration {
             });
             return { success: false, error: errorMessage };
         }
+        finally {
+            this.invalidateCache('kanban:');
+        }
+    }
+    // ==========================================================================
+    // GitHub Milestones Methods
+    // ==========================================================================
+    /**
+     * List milestones for a repository
+     */
+    async getMilestones(owner, repo, state = 'open', limit = 20) {
+        if (!this.octokit) {
+            return [];
+        }
+        const cacheKey = `milestones:${owner}:${repo}:${state}:${String(limit)}`;
+        const cached = this.getCached(cacheKey);
+        if (cached)
+            return cached;
+        try {
+            // GitHub REST API uses 'open' | 'closed' | 'all' for milestone state
+            const apiState = state === 'all' ? undefined : state;
+            const response = await this.octokit.issues.listMilestones({
+                owner,
+                repo,
+                state: apiState,
+                per_page: limit,
+                sort: 'due_on',
+                direction: 'asc',
+            });
+            const result = response.data.map((ms) => ({
+                number: ms.number,
+                title: ms.title,
+                description: ms.description ?? null,
+                state: ms.state === 'open' ? 'open' : 'closed',
+                url: ms.html_url,
+                dueOn: ms.due_on ?? null,
+                openIssues: ms.open_issues,
+                closedIssues: ms.closed_issues,
+                createdAt: ms.created_at,
+                updatedAt: ms.updated_at,
+                creator: ms.creator?.login ?? null,
+            }));
+            this.setCache(cacheKey, result);
+            return result;
+        }
+        catch (error) {
+            logger.error('Failed to get milestones', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+    /**
+     * Get a single milestone by number
+     */
+    async getMilestone(owner, repo, milestoneNumber) {
+        if (!this.octokit) {
+            return null;
+        }
+        const cacheKey = `milestone:${owner}:${repo}:${String(milestoneNumber)}`;
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const response = await this.octokit.issues.getMilestone({
+                owner,
+                repo,
+                milestone_number: milestoneNumber,
+            });
+            const ms = response.data;
+            const milestone = {
+                number: ms.number,
+                title: ms.title,
+                description: ms.description ?? null,
+                state: ms.state === 'open' ? 'open' : 'closed',
+                url: ms.html_url,
+                dueOn: ms.due_on ?? null,
+                openIssues: ms.open_issues,
+                closedIssues: ms.closed_issues,
+                createdAt: ms.created_at,
+                updatedAt: ms.updated_at,
+                creator: ms.creator?.login ?? null,
+            };
+            this.setCache(cacheKey, milestone);
+            return milestone;
+        }
+        catch (error) {
+            logger.error('Failed to get milestone', {
+                module: 'GitHub',
+                entityId: milestoneNumber,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Create a new milestone
+     */
+    async createMilestone(owner, repo, title, description, dueOn) {
+        if (!this.octokit) {
+            logger.error('Cannot create milestone: GitHub API not available', {
+                module: 'GitHub',
+            });
+            return null;
+        }
+        try {
+            const response = await this.octokit.issues.createMilestone({
+                owner,
+                repo,
+                title,
+                description,
+                due_on: dueOn,
+            });
+            const ms = response.data;
+            logger.info('Created GitHub milestone', {
+                module: 'GitHub',
+                entityId: ms.number,
+                context: { title, owner, repo },
+            });
+            return {
+                number: ms.number,
+                title: ms.title,
+                description: ms.description ?? null,
+                state: ms.state === 'open' ? 'open' : 'closed',
+                url: ms.html_url,
+                dueOn: ms.due_on ?? null,
+                openIssues: ms.open_issues,
+                closedIssues: ms.closed_issues,
+                createdAt: ms.created_at,
+                updatedAt: ms.updated_at,
+                creator: ms.creator?.login ?? null,
+            };
+        }
+        catch (error) {
+            logger.error('Failed to create milestone', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error),
+                context: { title, owner, repo },
+            });
+            return null;
+        }
+        finally {
+            this.invalidateCache(`milestones:${owner}:${repo}`);
+            this.invalidateCache('context:');
+        }
+    }
+    /**
+     * Update an existing milestone
+     */
+    async updateMilestone(owner, repo, milestoneNumber, updates) {
+        if (!this.octokit) {
+            logger.error('Cannot update milestone: GitHub API not available', {
+                module: 'GitHub',
+            });
+            return null;
+        }
+        try {
+            const response = await this.octokit.issues.updateMilestone({
+                owner,
+                repo,
+                milestone_number: milestoneNumber,
+                title: updates.title,
+                description: updates.description,
+                due_on: updates.dueOn === null ? undefined : updates.dueOn,
+                state: updates.state,
+            });
+            const ms = response.data;
+            logger.info('Updated GitHub milestone', {
+                module: 'GitHub',
+                entityId: milestoneNumber,
+                context: { owner, repo, updates: Object.keys(updates) },
+            });
+            return {
+                number: ms.number,
+                title: ms.title,
+                description: ms.description ?? null,
+                state: ms.state === 'open' ? 'open' : 'closed',
+                url: ms.html_url,
+                dueOn: ms.due_on ?? null,
+                openIssues: ms.open_issues,
+                closedIssues: ms.closed_issues,
+                createdAt: ms.created_at,
+                updatedAt: ms.updated_at,
+                creator: ms.creator?.login ?? null,
+            };
+        }
+        catch (error) {
+            logger.error('Failed to update milestone', {
+                module: 'GitHub',
+                entityId: milestoneNumber,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+        finally {
+            this.invalidateCache(`milestones:${owner}:${repo}`);
+            this.invalidateCache(`milestone:${owner}:${repo}:${String(milestoneNumber)}`);
+            this.invalidateCache('context:');
+        }
+    }
+    /**
+     * Delete a milestone
+     */
+    async deleteMilestone(owner, repo, milestoneNumber) {
+        if (!this.octokit) {
+            return { success: false, error: 'GitHub API not available' };
+        }
+        try {
+            await this.octokit.issues.deleteMilestone({
+                owner,
+                repo,
+                milestone_number: milestoneNumber,
+            });
+            logger.info('Deleted GitHub milestone', {
+                module: 'GitHub',
+                entityId: milestoneNumber,
+                context: { owner, repo },
+            });
+            return { success: true };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error('Failed to delete milestone', {
+                module: 'GitHub',
+                entityId: milestoneNumber,
+                error: errorMessage,
+            });
+            return { success: false, error: errorMessage };
+        }
+        finally {
+            this.invalidateCache(`milestones:${owner}:${repo}`);
+            this.invalidateCache(`milestone:${owner}:${repo}:${String(milestoneNumber)}`);
+            this.invalidateCache('context:');
+        }
+    }
+    // ==========================================================================
+    // Repository Insights/Traffic Methods
+    // ==========================================================================
+    /**
+     * Get a cached value with a custom TTL.
+     * Used for traffic endpoints which change slowly (10-min TTL).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- T is needed at call sites for type-safe casts
+    getCachedWithTtl(key, ttlMs) {
+        const entry = this.apiCache.get(key);
+        if (entry && Date.now() - entry.timestamp < ttlMs) {
+            return entry.data;
+        }
+        if (entry) {
+            this.apiCache.delete(key);
+        }
+        return undefined;
+    }
+    /**
+     * Get repository statistics (stars, forks, watchers).
+     * Uses a single GET /repos/{owner}/{repo} API call.
+     */
+    async getRepoStats(owner, repo) {
+        if (!this.octokit) {
+            return null;
+        }
+        const cacheKey = `repostats:${owner}:${repo}`;
+        const cached = this.getCachedWithTtl(cacheKey, TRAFFIC_CACHE_TTL_MS);
+        if (cached)
+            return cached;
+        try {
+            const response = await this.octokit.repos.get({ owner, repo });
+            const data = response.data;
+            const result = {
+                stars: data.stargazers_count,
+                forks: data.forks_count,
+                watchers: data.subscribers_count,
+                openIssues: data.open_issues_count,
+                size: data.size,
+                defaultBranch: data.default_branch,
+            };
+            this.setCache(cacheKey, result);
+            return result;
+        }
+        catch (error) {
+            logger.error('Failed to get repo stats', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error),
+                context: { owner, repo },
+            });
+            return null;
+        }
+    }
+    /**
+     * Get aggregated traffic data (14-day rolling clones + views).
+     * Combines GET /repos/{owner}/{repo}/traffic/clones and /traffic/views.
+     * Requires push access to the repository.
+     */
+    async getTrafficData(owner, repo) {
+        if (!this.octokit) {
+            return null;
+        }
+        const cacheKey = `traffic:${owner}:${repo}`;
+        const cached = this.getCachedWithTtl(cacheKey, TRAFFIC_CACHE_TTL_MS);
+        if (cached)
+            return cached;
+        try {
+            const [clonesRes, viewsRes] = await Promise.all([
+                this.octokit.rest.repos.getClones({ owner, repo }),
+                this.octokit.rest.repos.getViews({ owner, repo }),
+            ]);
+            const clonesDays = clonesRes.data.clones?.length ?? 0;
+            const viewsDays = viewsRes.data.views?.length ?? 0;
+            const result = {
+                clones: {
+                    total: clonesRes.data.count,
+                    unique: clonesRes.data.uniques,
+                    dailyAvg: clonesDays > 0 ? Math.round(clonesRes.data.count / clonesDays) : 0,
+                },
+                views: {
+                    total: viewsRes.data.count,
+                    unique: viewsRes.data.uniques,
+                    dailyAvg: viewsDays > 0 ? Math.round(viewsRes.data.count / viewsDays) : 0,
+                },
+                period: '14 days',
+            };
+            this.setCache(cacheKey, result);
+            return result;
+        }
+        catch (error) {
+            logger.error('Failed to get traffic data', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error),
+                context: { owner, repo },
+            });
+            return null;
+        }
+    }
+    /**
+     * Get top referrer sources for the repository (14-day rolling).
+     * Requires push access to the repository.
+     */
+    async getTopReferrers(owner, repo, limit = 5) {
+        if (!this.octokit) {
+            return [];
+        }
+        const cacheKey = `referrers:${owner}:${repo}`;
+        const cached = this.getCachedWithTtl(cacheKey, TRAFFIC_CACHE_TTL_MS);
+        if (cached)
+            return cached.slice(0, limit);
+        try {
+            const response = await this.octokit.rest.repos.getTopReferrers({ owner, repo });
+            const result = response.data.map((r) => ({
+                referrer: r.referrer,
+                count: r.count,
+                uniques: r.uniques,
+            }));
+            this.setCache(cacheKey, result);
+            return result.slice(0, limit);
+        }
+        catch (error) {
+            logger.error('Failed to get top referrers', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error),
+                context: { owner, repo },
+            });
+            return [];
+        }
+    }
+    /**
+     * Get popular repository paths (14-day rolling).
+     * Requires push access to the repository.
+     */
+    async getPopularPaths(owner, repo, limit = 5) {
+        if (!this.octokit) {
+            return [];
+        }
+        const cacheKey = `paths:${owner}:${repo}`;
+        const cached = this.getCachedWithTtl(cacheKey, TRAFFIC_CACHE_TTL_MS);
+        if (cached)
+            return cached.slice(0, limit);
+        try {
+            const response = await this.octokit.rest.repos.getTopPaths({ owner, repo });
+            const result = response.data.map((p) => ({
+                path: p.path,
+                title: p.title,
+                count: p.count,
+                uniques: p.uniques,
+            }));
+            this.setCache(cacheKey, result);
+            return result.slice(0, limit);
+        }
+        catch (error) {
+            logger.error('Failed to get popular paths', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error),
+                context: { owner, repo },
+            });
+            return [];
+        }
     }
 }
 //# sourceMappingURL=GitHubIntegration.js.map