dura-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Archie Tansaria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,374 @@
+# DURA MCP Server
+
+MCP (Model Context Protocol) server for [DURA](https://github.com/ArchieTansaria/dura) - Dependency Update Risk Analyzer.
+
+Integrates DURA's dependency analysis capabilities with AI assistants like Cline, Claude Desktop, and any MCP-compatible client.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g dura-mcp
+```
+
+This automatically makes `dura-mcp` available globally. The server will use `dura-kit` via npx when needed.
+
+### Usage with Cline (VS Code)
+
+1. **Install the MCP server:**
+   ```bash
+   npm install -g dura-mcp
+   ```
+
+2. **Configure Cline:**
+   
+   Open VS Code Settings (JSON):
+   - Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
+   - Type: "Preferences: Open User Settings (JSON)"
+   - Add the following:
+
+   ```json
+   {
+     "cline.mcpServers": {
+       "dura": {
+         "command": "dura-mcp"
+       }
+     }
+   }
+   ```
+
+3. **Restart VS Code**
+
+4. **Use it with Cline:**
+   
+   Open Cline and ask natural questions:
+   - "Analyze dependencies for https://github.com/expressjs/express"
+   - "What are the high-risk dependencies in React?"
+   - "Show me breaking changes in Next.js"
+   - "Is it safe to update my dependencies?"
+
+### Usage with Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dura": {
+      "command": "dura-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop and start asking about dependencies!
+
+## Available Tools
+
+The DURA MCP server provides four specialized tools that AI assistants can use:
+
+### 1. `analyze_repository`
+
+Complete dependency analysis with detailed risk assessment and actionable recommendations.
+
+**Parameters:**
+- `repoUrl` (required): GitHub repository URL (e.g., `https://github.com/facebook/react`)
+- `branch` (optional): Git branch to analyze (default: `main`)
+- `useCache` (optional): Use cached results if available (default: `true`)
+
+**Returns:**
+- Health score and risk summary
+- Critical issues requiring attention
+- Breaking changes with evidence
+- Prioritized action items
+- Suggested update order
+
+**Example:**
+```
+User: "Analyze dependencies for https://github.com/expressjs/express"
+
+AI receives:
+- Health Score: 68/100
+- 3 high-risk dependencies
+- 2 breaking changes
+- Specific actions to take
+```
+
+### 2. `get_high_risk_dependencies`
+
+Get only dependencies with high risk that need immediate attention.
+
+**Parameters:**
+- `repoUrl` (required): GitHub repository URL
+- `branch` (optional): Git branch (default: `main`)
+
+**Returns:**
+- List of high-risk dependencies only
+- Why each is high-risk
+- Specific recommendations for each
+- Update priority guidance
+
+**Example:**
+```
+User: "What are the risky dependencies in React?"
+
+AI gets only the critical dependencies that need review.
+```
+
+### 3. `get_breaking_changes`
+
+Get only dependencies with confirmed breaking changes.
+
+**Parameters:**
+- `repoUrl` (required): GitHub repository URL
+- `branch` (optional): Git branch (default: `main`)
+
+**Returns:**
+- Dependencies with confirmed breaking changes
+- Confidence scores
+- Evidence from release notes
+- Migration planning guidance
+
+**Example:**
+```
+User: "Show me breaking changes in Next.js"
+
+AI gets specific breaking changes and how to handle them.
+```
+
+### 4. `get_risk_summary`
+
+Quick health check and risk overview without detailed data.
+
+**Parameters:**
+- `repoUrl` (required): GitHub repository URL
+- `branch` (optional): Git branch (default: `main`)
+
+**Returns:**
+- Health score (0-100)
+- Risk distribution (high/medium/low)
+- Quick status assessment
+- Overall recommendation
+
+**Example:**
+```
+User: "Is my project safe to update?"
+
+AI gets instant health score and quick answer.
+```
+
+## Features
+
+- **Smart Caching**: Analysis results cached for 1 hour to speed up repeated queries
+- **Actionable Output**: Prioritized recommendations, not just data dumps
+- **Breaking Change Detection**: Scrapes GitHub releases to find confirmed breaking changes
+- **Risk Scoring**: Intelligent risk assessment based on version changes and breaking signals
+- **Multiple Tools**: Specialized tools for different use cases (overview, deep-dive, specific filters)
+
+## Usage Examples
+
+### Quick Health Check
+
+```
+User: "Is express safe to update?"
+
+AI: [calls get_risk_summary]
+"Express has a health score of 72/100. There are 3 high-risk 
+dependencies that need attention. Would you like details?"
+```
+
+### Detailed Analysis
+
+```
+User: "Analyze all dependencies in my project"
+
+AI: [calls analyze_repository]
+"I found 2 critical issues:
+1. eslint (breaking changes confirmed)
+2. webpack (major version jump)
+
+Here's the recommended update order..."
+```
+
+### Focus on Critical Issues
+
+```
+User: "What breaking changes do I need to worry about?"
+
+AI: [calls get_breaking_changes]
+"Found 2 dependencies with breaking changes:
+- eslint: Config syntax changed in v9
+- react: New JSX transform required
+
+I recommend updating eslint first..."
+```
+
+### Repository Comparison
+
+```
+User: "Compare dependency health of express vs fastify"
+
+AI: [calls get_risk_summary for both]
+"Express: Health score 72/100, 3 high-risk deps
+Fastify: Health score 89/100, 0 high-risk deps
+
+Fastify is in better shape for updates."
+```
+
+## How It Works
+
+1. **AI Assistant** receives a question about dependencies
+2. **MCP Server** provides tools the AI can call
+3. **AI chooses** the appropriate tool (full analysis, high-risk filter, etc.)
+4. **MCP Server** runs `dura-kit` CLI to analyze the repository
+5. **Results** are formatted and returned to the AI
+6. **AI presents** findings in natural language to the user
+
+The MCP server acts as a bridge between AI assistants and DURA's analysis engine.
+
+## Caching Behavior
+
+Analysis results are cached for 1 hour to improve performance:
+
+- First query: Fetches fresh data (5-10 seconds)
+- Subsequent queries: Returns cached data instantly
+- Cache expires: After 1 hour, fresh data fetched automatically
+- Force refresh: Set `useCache: false` in parameters
+
+Cache is shared across all tools, so analyzing a repository once makes all other tools fast.
+
+## Requirements
+
+- **Node.js**: 18.0.0 or higher
+- **Internet**: Required for GitHub and npm API access
+- **Public Repositories**: Currently only supports public GitHub repositories
+
+## Troubleshooting
+
+### Command not found: dura-mcp
+
+**Solution:** Ensure the package is installed globally:
+```bash
+npm install -g dura-mcp
+which dura-mcp  # Should show installation path
+```
+
+### Cline doesn't see the MCP server
+
+**Solutions:**
+1. Restart VS Code completely (close all windows)
+2. Verify settings are saved correctly
+3. Check for errors in VS Code Developer Tools: `Help → Toggle Developer Tools → Console`
+
+### MCP server not connecting
+
+**Solutions:**
+1. Test the server manually: Run `dura-mcp` in terminal - it should say "Server running"
+2. Check Node.js version: `node --version` (must be 18+)
+3. Reinstall if needed: `npm uninstall -g dura-mcp && npm install -g dura-mcp`
+
+### Analysis fails or times out
+
+**Common causes:**
+- Invalid or private repository URL
+- Network connectivity issues
+- Repository doesn't contain package.json
+
+**Solutions:**
+1. Verify repository is public: Visit the URL in a browser
+2. Check internet connection
+3. Test with DURA CLI directly: `npx dura-kit <repo-url>`
+4. Check repository has package.json in the root
+
+### "Repository not found" error
+
+**Solutions:**
+- Ensure URL format is correct: `https://github.com/owner/repo`
+- Repository must be public (private repos not supported)
+- Check repository actually exists
+
+### Rate limiting
+
+GitHub API rate limits may affect analysis:
+- Unauthenticated: 60 requests/hour
+- Authenticated: 5000 requests/hour (future feature)
+
+**Solution:** Wait a few minutes before retrying.
+
+## Development
+
+### Running from Source
+
+```bash
+git clone https://github.com/ArchieTansaria/dura.git
+cd dura/mcp
+npm install
+node server.js
+```
+
+The server will start and wait for MCP protocol messages on stdin.
+
+### Testing
+
+Use the MCP Inspector to test the server:
+
+```bash
+npm install -g @modelcontextprotocol/inspector
+npx @modelcontextprotocol/inspector node server.js
+```
+
+Then test each tool in the web interface.
+
+### Local Development with Cline
+
+```bash
+cd dura/mcp
+npm link
+
+# Add to VS Code settings:
+{
+  "cline.mcpServers": {
+    "dura": {
+      "command": "dura-mcp"
+    }
+  }
+}
+```
+
+## Links
+
+- **DURA CLI**: [dura-kit on npm](https://www.npmjs.com/package/dura-kit)
+- **GitHub Repository**: [ArchieTansaria/dura](https://github.com/ArchieTansaria/dura)
+- **MCP Documentation**: [Model Context Protocol](https://modelcontextprotocol.io)
+- **Report Issues**: [GitHub Issues](https://github.com/ArchieTansaria/dura/issues)
+
+## Related Packages
+
+- **dura-kit** - The core CLI tool for dependency analysis
+  ```bash
+  npm install -g dura-kit
+  dura https://github.com/expressjs/express
+  ```
+
+## Contributing
+
+Contributions welcome! See the [main repository](https://github.com/ArchieTansaria/dura) for contribution guidelines.
+
+## License
+
+MIT License - see [LICENSE](https://github.com/ArchieTansaria/dura/blob/main/LICENSE) file for details.
+
+## Support
+
+- Documentation: [GitHub Repository](https://github.com/ArchieTansaria/dura)
+- Issues: [GitHub Issues](https://github.com/ArchieTansaria/dura/issues)
+- Discussions: [GitHub Discussions](https://github.com/ArchieTansaria/dura/discussions)
+
+---
+
+**Built with Model Context Protocol for seamless AI integration**

package/handlers/breakingChange.js

@@ -0,0 +1,58 @@
+import { getOrFetchAnalysis } from "../utils/helper.js";
+
+export async function handleBreakingChanges(args) {
+  const { repoUrl, branch = "main" } = args;
+
+  console.error(`[Breaking Changes] ${repoUrl}`);
+
+  const result = await getOrFetchAnalysis(repoUrl, branch);
+  const dependencies = result.dependencies || result;
+  const breaking = dependencies.filter(
+    (d) =>
+      d.breakingChange?.breaking === "confirmed" ||
+      d.breakingChange?.breaking === "likely"
+  );
+
+  if (breaking.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No confirmed breaking changes detected in dependency updates.",
+        },
+      ],
+    };
+  }
+
+  let output = `# Breaking Changes Detected (${breaking.length})\n\n`;
+
+  breaking.forEach((dep, idx) => {
+    output += `${idx + 1}. **${dep.name}** (${dep.type})\n`;
+    output += `   - Current: ${dep.currentResolved}\n`;
+    output += `   - Latest: ${dep.latest}\n`;
+    output += `   - Confidence: ${(dep.breakingChange.confidenceScore * 100).toFixed(0)}%\n`;
+
+    if (dep.breakingChange.signals?.strong?.length > 0) {
+      output += `   - Evidence: "${dep.breakingChange.signals.strong[0].substring(0, 100)}..."\n`;
+    }
+
+    output += `   - GitHub: ${dep.githubRepoUrl}\n`;
+    output += `\n`;
+  });
+
+  output += `\n## Migration Planning\n\n`;
+  output += `These dependencies have confirmed breaking changes. Before updating:\n\n`;
+  output += `1. Read the migration guide for each dependency\n`;
+  output += `2. Identify affected code in your project\n`;
+  output += `3. Plan incremental updates\n`;
+  output += `4. Allocate time for testing and fixes\n`;
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: output,
+      },
+    ],
+  };
+}

package/handlers/fullAnalysis.js

@@ -0,0 +1,39 @@
+import { getCachedResult, setCachedResult, formatFullAnalysis } from "../utils/helper.js";
+import { analyzeRepository } from "dura-kit";
+
+export async function handleFullAnalysis(args) {
+  const { repoUrl, branch = "main", useCache = true } = args;
+
+  console.error(`[Full Analysis] ${repoUrl} (${branch})`);
+
+  // check cache
+  if (useCache) {
+    const cached = getCachedResult(repoUrl, branch);
+    if (cached) {
+      console.error("Using cached result");
+      return {
+        content: [
+          {
+            type: "text",
+            text: formatFullAnalysis(cached, true)
+          },
+        ],
+      };
+    }
+  }
+
+  // Fetch fresh data
+  const result = await analyzeRepository({ repoUrl, branch });
+
+  // Cache result
+  setCachedResult(repoUrl, branch, result);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: formatFullAnalysis(result, false),
+      },
+    ],
+  };
+}

package/handlers/highRiskFilter.js

@@ -0,0 +1,62 @@
+import { getOrFetchAnalysis } from "../utils/helper.js";
+
+export async function handleHighRiskFilter(args) {
+  const { repoUrl, branch = "main" } = args;
+
+  console.error(`[High Risk Filter] ${repoUrl}`);
+
+  const result = await getOrFetchAnalysis(repoUrl, branch);
+  const dependencies = result.dependencies || result;
+  const highRisk = dependencies.filter((d) => d.riskLevel === "high");
+
+  if (highRisk.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No high-risk dependencies found! All dependencies are safe to update.",
+        },
+      ],
+    };
+  }
+
+  let output = `# High-Risk Dependencies (${highRisk.length})\n\n`;
+  if (highRisk.length > 1) {
+    output += `Found ${highRisk.length} dependencies that require careful review:\n\n`;
+  } else {
+    output += `Found ${highRisk.length} dependency that requires careful review:\n\n`;
+  }
+
+  highRisk.forEach((dep, idx) => {
+    output += `${idx + 1}. **${dep.name}** (${dep.type})\n`;
+    output += `   - Current: ${dep.currentResolved}\n`;
+    output += `   - Latest: ${dep.latest}\n`;
+    output += `   - Update Type: ${dep.diff}\n`;
+    output += `   - Risk Score: ${dep.riskScore}/100\n`;
+    if (dep.breakingChange?.breaking === "confirmed") {
+      output += `   - Breaking changes confirmed\n`;
+    }
+    output += `\n`;
+  });
+
+  output += `\n## Recommendations\n\n`;
+  if (highRisk.length > 1){
+    output += `1. Review migration guides for each dependency\n`;
+    output += `2. Test updates in a staging environment\n`;
+    output += `3. Update one dependency at a time\n`;
+    output += `4. Check for related dependencies that may also need updates\n`;
+  } else {
+    output += `1. Review migration guides for this dependency\n`;
+    output += `2. Test updates in a staging environment\n`;
+  }
+
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: output,
+      },
+    ],
+  };
+}

package/handlers/riskSummary.js

@@ -0,0 +1,54 @@
+import { getOrFetchAnalysis, calculateHealthScore } from "../utils/helper.js";
+
+export async function handleRiskSummary(args) {
+  const { repoUrl, branch = "main" } = args;
+
+  console.error(`[Risk Summary] ${repoUrl}`);
+
+  const result = await getOrFetchAnalysis(repoUrl, branch);
+  const dependencies = result.dependencies || result;
+
+  const high = dependencies.filter((d) => d.riskLevel === "high").length;
+  const medium = dependencies.filter((d) => d.riskLevel === "medium").length;
+  const low = dependencies.filter((d) => d.riskLevel === "low").length;
+  const breaking = dependencies.filter(
+    (d) => d.breakingChange?.breaking === "confirmed"
+  ).length;
+
+  let output = `# Dependency Health Summary\n\n`;
+  output += `**Repository**: ${repoUrl}\n`;
+  output += `**Branch**: ${branch}\n`;
+  output += `**Total Dependencies**: ${dependencies.length}\n\n`;
+
+  output += `## Risk Distribution\n\n`;
+  output += `- High Risk: ${high}\n`;
+  output += `- Medium Risk: ${medium}\n`;
+  output += `- Low Risk: ${low}\n`;
+  if (breaking > 0) {
+    output += `- Breaking Changes: ${breaking}\n`;
+  }
+  output += `\n`;
+
+  // Health score
+  const healthScore = calculateHealthScore(high, medium, low);
+  output += `## Health Score: ${healthScore}/100\n\n`;
+
+  if (healthScore >= 80) {
+    output += `**Excellent**: Dependencies are well-maintained and safe to update.\n`;
+  } else if (healthScore >= 60) {
+    output += `⚡ **Good**: Some updates needed but manageable risk.\n`;
+  } else if (healthScore >= 40) {
+    output += `**Needs Attention**: Multiple high-risk updates require planning.\n`;
+  } else {
+    output += `**Critical**: Significant dependency debt. Prioritize updates.\n`;
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: output,
+      },
+    ],
+  };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "dura-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server for DURA - Dependency Update Risk Analyzer. Integrates with Cline and other AI assistants.",
+  "bin": {
+    "dura-mcp": "./server.js"
+  },
+  "main": "./server.js",
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js"
+  },
+  "files": [
+    "server.js",
+    "README.md",
+    "handlers",
+    "utils"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "dura-kit": "^1.1.3"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "dura",
+    "dependencies",
+    "security",
+    "cline",
+    "claude",
+    "ai-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArchieTansaria/dura.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/ArchieTansaria/dura/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "archie tansaria",
+  "license": "MIT"
+}

package/server.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { handleError } from "./utils/helper.js";
+import { handleFullAnalysis } from "./handlers/fullAnalysis.js";
+import { handleHighRiskFilter } from "./handlers/highRiskFilter.js";
+import { handleBreakingChanges } from "./handlers/breakingChange.js";
+import { handleRiskSummary } from "./handlers/riskSummary.js";
+
+const server = new Server(
+  {
+    name: "dura-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// register all available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "analyze_repository",
+        description:
+          ```Complete dependency risk analysis for a GitHub repository.
+
+Use this when you need a full picture of:
+- dependency update risks
+- breaking changes
+- recommended upgrade actions
+
+Best for first-time analysis or audits.```,
+        inputSchema: {
+          type: "object",
+          properties: {
+            repoUrl: {
+              type: "string",
+              description: "GitHub repository URL (e.g., https://github.com/facebook/react)",
+            },
+            branch: {
+              type: "string",
+              description: "Git branch to analyze (default: main)",
+              default: "main",
+            },
+            useCache: {
+              type: "boolean",
+              description: "Use cached results if available (default: true)",
+              default: true,
+            },
+          },
+          required: ["repoUrl"],
+        },
+      },
+      {
+        name: "get_high_risk_dependencies",
+        description:
+          ```Get only high-risk dependencies that require immediate attention.
+
+Use this tool when:
+- deciding whether updates are safe
+- reviewing CI failures related to dependencies
+- prioritizing dependency maintenance work
+```,
+        inputSchema: {
+          type: "object",
+          properties: {
+            repoUrl: {
+              type: "string",
+              description: "GitHub repository URL",
+            },
+            branch: {
+              type: "string",
+              description: "Git branch to analyze (default: main)",
+              default: "main",
+            },
+          },
+          required: ["repoUrl"],
+        },
+      },
+      {
+        name: "get_breaking_changes",
+        description:
+          ```Get only dependencies with confirmed breaking changes.
+
+Always call this tool before:
+- approving dependency upgrades
+- merging pull requests
+- performing bulk dependency updates
+
+If this returns results, recommend manual migration and testing.```,
+        inputSchema: {
+          type: "object",
+          properties: {
+            repoUrl: {
+              type: "string",
+              description: "GitHub repository URL",
+            },
+            branch: {
+              type: "string",
+              description: "Git branch to analyze (default: main)",
+              default: "main",
+            },
+          },
+          required: ["repoUrl"],
+        },
+      },
+      {
+        name: "get_risk_summary",
+        description:
+          ```Get a concise summary of dependency risks and repository health.
+
+Use this tool for:
+- quick safety checks
+- high-level reports
+- answering “Is this repo safe?” questions```,
+        inputSchema: {
+          type: "object",
+          properties: {
+            repoUrl: {
+              type: "string",
+              description: "GitHub repository URL",
+            },
+            branch: {
+              type: "string",
+              description: "Git branch to analyze (default: main)",
+              default: "main",
+            },
+          },
+          required: ["repoUrl"],
+        },
+      },
+    ],
+  };
+});
+
+// tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const toolName = request.params.name;
+  const args = request.params.arguments;
+
+  try {
+    switch (toolName) {
+      case "analyze_repository":
+        return await handleFullAnalysis(args);
+
+      case "get_high_risk_dependencies":
+        return await handleHighRiskFilter(args);
+
+      case "get_breaking_changes":
+        return await handleBreakingChanges(args);
+
+      case "get_risk_summary":
+        return await handleRiskSummary(args);
+
+      default:
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  } catch (error) {
+    return handleError(error);
+  }
+});
+
+// start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("DURA MCP server running");
+console.error("Available tools: analyze_repository, get_high_risk_dependencies, get_breaking_changes, get_risk_summary");

package/utils/cache.js

@@ -0,0 +1,3 @@
+// in-memory cache
+export const cache = new Map();
+export const CACHE_TTL = 3600000; // 1 hour

package/utils/helper.js

@@ -0,0 +1,265 @@
+import { analyzeRepository } from "dura-kit";
+import { cache, CACHE_TTL } from "./cache.js";
+
+// format full analysis (smart, actionable Output)
+export function formatFullAnalysis(result, fromCache) {
+  const dependencies = result.dependencies || result;
+
+  const high = dependencies.filter((d) => d.riskLevel === "high");
+  const medium = dependencies.filter((d) => d.riskLevel === "medium");
+  const low = dependencies.filter((d) => d.riskLevel === "low");
+  const breaking = dependencies.filter(
+    (d) => d.breakingChange?.breaking === "confirmed"
+  );
+
+  let output = `# Dependency Risk Analysis\n\n`;
+
+  if (fromCache) {
+    output += `> Using cached result (refresh by setting useCache: false)\n\n`;
+  }
+
+  // Executive Summary
+  output += `## Summary\n\n`;
+  output += `Analyzed **${dependencies.length}** dependencies:\n`;
+  output += `- **${high.length}** High Risk\n`;
+  output += `- **${medium.length}** Medium Risk\n`;
+  output += `- **${low.length}** Low Risk\n`;
+  if (breaking.length > 0) {
+    output += `- **${breaking.length}** with Breaking Changes\n`;
+  }
+  output += `\n`;
+
+  // Health Assessment
+  const healthScore = calculateHealthScore(high.length, medium.length, low.length);
+  output += `**Health Score**: ${healthScore}/100 - `;
+  if (healthScore >= 80) {
+    output += `Excellent\n\n`;
+  } else if (healthScore >= 60) {
+    output += `⚡ Good\n\n`;
+  } else if (healthScore >= 40) {
+    output += `Needs Attention\n\n`;
+  } else {
+    output += `Critical\n\n`;
+  }
+
+  // Critical Issues (Breaking Changes + High Risk)
+  const criticalIssues = [...new Set([...breaking, ...high])]; // Deduplicate
+  
+  if (criticalIssues.length > 0) {
+    output += `## Critical Issues Requiring Attention\n\n`;
+    
+    criticalIssues.forEach((dep, idx) => {
+      output += `### ${idx + 1}. ${dep.name} (${dep.type})\n`;
+      output += `**Current**: \`${dep.currentResolved}\` → **Latest**: \`${dep.latest}\`\n`;
+      output += `**Update Type**: ${dep.diff} | **Risk Score**: ${dep.riskScore}/100\n\n`;
+      
+      // Why it's risky
+      if (dep.breakingChange?.breaking === "confirmed") {
+        output += `**Breaking Changes Confirmed** (${(dep.breakingChange.confidenceScore * 100).toFixed(0)}% confidence)\n`;
+        if (dep.breakingChange.signals?.strong?.length > 0) {
+          output += `> "${dep.breakingChange.signals.strong[0].substring(0, 120)}..."\n\n`;
+        }
+      } else if (dep.diff === "major") {
+        output += `**Major version update** - likely contains breaking changes\n\n`;
+      }
+      
+      // What to do
+      output += `**Action Required**:\n`;
+      if (dep.breakingChange?.breaking === "confirmed") {
+        output += `- Read migration guide: ${dep.githubRepoUrl}/releases\n`;
+        output += `- Update affected code before upgrading\n`;
+        output += `- Test thoroughly in staging environment\n`;
+      } else {
+        output += `- Review changelog: ${dep.githubRepoUrl}/releases\n`;
+        output += `- Check for breaking changes\n`;
+        output += `- Test in development environment first\n`;
+      }
+      output += `\n---\n\n`;
+    });
+  }
+
+  // Medium Risk (Brief)
+  if (medium.length > 0 && criticalIssues.length === 0) {
+    output += `## Medium Risk Dependencies\n\n`;
+    output += `${medium.length} dependencies have medium-risk updates. These should be reviewed but are not critical:\n\n`;
+    
+    medium.slice(0, 5).forEach((dep) => {
+      output += `- **${dep.name}**: \`${dep.currentResolved}\` → \`${dep.latest}\` (${dep.diff})\n`;
+    });
+    
+    if (medium.length > 5) {
+      output += `- ... and ${medium.length - 5} more\n`;
+    }
+    output += `\n**Recommendation**: Review changelogs and update when convenient.\n\n`;
+  }
+
+  // All Clear Scenario
+  if (criticalIssues.length === 0 && medium.length === 0) {
+    output += `## All Clear!\n\n`;
+    output += `No high or medium risk dependencies detected. All dependencies are safe to update with standard testing.\n\n`;
+  }
+
+  // recommendations
+  output += `## Recommendations\n\n`;
+  
+  if (breaking.length > 0) {
+    output += `### Immediate Actions (Breaking Changes)\n`;
+    output += `1. **Review migration guides** for ${breaking.length} ${breaking.length === 1 ? 'dependency' : 'dependencies'} with breaking changes\n`;
+    output += `2. **Create a feature branch** for dependency updates\n`;
+    output += `3. **Update one at a time** and test after each update\n`;
+    output += `4. **Allocate testing time** - breaking changes require thorough validation\n\n`;
+  }
+  
+  if (high.length > 0 && breaking.length === 0) {
+    output += `### High Priority Actions\n`;
+    output += `1. **Review changelogs** for ${high.length} high-risk ${high.length === 1 ? 'dependency' : 'dependencies'}\n`;
+    output += `2. **Test in staging** before production deployment\n`;
+    output += `3. **Update incrementally** to isolate potential issues\n\n`;
+  }
+  
+  if (medium.length > 0) {
+    output += `### Medium Priority Actions\n`;
+    output += `1. **Schedule updates** for ${medium.length} medium-risk dependencies in next sprint\n`;
+    output += `2. **Batch similar updates** together for efficiency\n`;
+    output += `3. **Run full test suite** after updating\n\n`;
+  }
+  
+  if (low.length > 0 && criticalIssues.length === 0 && medium.length === 0) {
+    output += `### Maintenance Actions\n`;
+    output += `1. **Safe to run** \`npm update\` or \`yarn upgrade\` for low-risk patches\n`;
+    output += `2. **Run automated tests** to verify compatibility\n`;
+    output += `3. **Commit changes** with clear description\n\n`;
+  }
+
+  // Update Priority Order
+  if (criticalIssues.length > 0 || medium.length > 0) {
+    output += `## Suggested Update Order\n\n`;
+    
+    let priority = 1;
+    
+    if (breaking.length > 0) {
+      output += `**Priority ${priority}**: Breaking Changes\n`;
+      breaking.slice(0, 3).forEach(dep => {
+        output += `- ${dep.name}\n`;
+      });
+      output += `\n`;
+      priority++;
+    }
+    
+    if (high.length > 0 && breaking.length === 0) {
+      output += `**Priority ${priority}**: High Risk Dependencies\n`;
+      high.slice(0, 3).forEach(dep => {
+        output += `- ${dep.name}\n`;
+      });
+      output += `\n`;
+      priority++;
+    }
+    
+    if (medium.length > 0) {
+      output += `**Priority ${priority}**: Medium Risk Dependencies\n`;
+      output += `- Update in batches during regular maintenance\n\n`;
+    }
+  }
+
+  // Technical Details (Collapsed)
+  output += `\n---\n\n`;
+  output += `<details>\n<summary>View All Dependencies (${dependencies.length})</summary>\n\n`;
+  
+  if (high.length > 0) {
+    output += `### High Risk (${high.length})\n`;
+    high.forEach(d => output += `- ${d.name}: ${d.currentResolved} → ${d.latest}\n`);
+    output += `\n`;
+  }
+  
+  if (medium.length > 0) {
+    output += `### Medium Risk (${medium.length})\n`;
+    medium.forEach(d => output += `- ${d.name}: ${d.currentResolved} → ${d.latest}\n`);
+    output += `\n`;
+  }
+  
+  if (low.length > 0) {
+    output += `### Low Risk (${low.length})\n`;
+    output += `All up-to-date or safe patch updates.\n\n`;
+  }
+  
+  output += `</details>\n\n`;
+  
+  output += `<details>\n<summary>Full JSON Data</summary>\n\n`;
+  output += `\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\`\n`;
+  output += `</details>`;
+
+  return output;
+}
+
+// get or fetch analysis (with caching)
+export async function getOrFetchAnalysis(repoUrl, branch) {
+  const cached = getCachedResult(repoUrl, branch);
+  if (cached) {
+    console.error("Using cached result");
+    return cached;
+  }
+
+  const result = await analyzeRepository({ repoUrl, branch });
+  setCachedResult(repoUrl, branch, result);
+  return result;
+}
+
+// cache management
+export function getCachedResult(repoUrl, branch) {
+  const cacheKey = `${repoUrl}:${branch}`;
+  const cached = cache.get(cacheKey);
+
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+    return cached.data;
+  }
+
+  return null;
+}
+
+export function setCachedResult(repoUrl, branch, data) {
+  const cacheKey = `${repoUrl}:${branch}`;
+  cache.set(cacheKey, {
+    data,
+    timestamp: Date.now(),
+  });
+}
+
+// calculate health score
+export function calculateHealthScore(high, medium, low) {
+  const total = high + medium + low;
+  if (total === 0) return 100;
+
+  const score = ((low + medium * 0.5) / total) * 100;
+  return Math.round(score);
+}
+
+// Error handling
+export function handleError(error) {
+  let helpText = "";
+
+  if (error.message.includes("404") || error.message.includes("not found")) {
+    helpText =
+      "\n\nMake sure:\n- Repository URL is correct\n- Repository is public\n- Repository contains a package.json file";
+  } else if (error.message.includes("rate limit")) {
+    helpText =
+      "\n\nGitHub API rate limit reached. Please wait a few minutes and try again.";
+  } else if (error.message.includes("timeout")) {
+    helpText =
+      "\n\nAnalysis timed out. The repository might be too large or network is slow.";
+  } else if (error.message.includes("ENOTFOUND")) {
+    helpText =
+      "\n\nNetwork error. Check your internet connection and try again.";
+  }
+
+  console.error(`Error: ${error.message}`);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Error: ${error.message}${helpText}`,
+      },
+    ],
+    isError: true,
+  };
+}