agent-enderun 0.1.10 → 0.2.0

package/packages/framework-mcp/dist/schemas.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+export const SECURITY_AUDIT_ARGS_SCHEMA = z.object({
+    path: z.string().default("."),
+});
+export const SEARCH_CODEBASE_ARGS_SCHEMA = z.object({
+    query: z.string().min(1).max(300),
+    extension: z
+        .string()
+        .regex(/^[a-z0-9]+$/i)
+        .default("ts"),
+});
+export const UPDATE_MEMORY_ARGS_SCHEMA = z.object({
+    section: z.enum(["CURRENT STATUS", "HISTORY", "ACTIVE TASKS"]),
+    content: z.string().min(1),
+});
+export const ANALYZE_DEPENDENCIES_ARGS_SCHEMA = z.object({
+    path: z.string().min(1),
+});
+export const LOG_AGENT_ACTION_ARGS_SCHEMA = z.object({
+    agent: z.string().min(1),
+    action: z.string().min(1),
+    requestId: z.string().min(1),
+    files: z.array(z.string()).default([]),
+    status: z.enum(["SUCCESS", "FAILURE"]),
+    summary: z.string().min(1),
+    details: z.record(z.any()).default({}),
+});
+export const SEND_AGENT_MESSAGE_ARGS_SCHEMA = z.object({
+    to: z.string().min(1),
+    message: z.string().min(1),
+    traceId: z.string().min(1),
+});
+export const SEARCH_KNOWLEDGE_BASE_ARGS_SCHEMA = z.object({
+    query: z.string().min(1),
+});
+export const UPDATE_KNOWLEDGE_BASE_ARGS_SCHEMA = z.object({
+    topic: z.string().min(1),
+    content: z.string().min(1),
+});
+export const ANALYZE_DATABASE_SCHEMA_ARGS_SCHEMA = z.object({
+    path: z.string().default("apps/backend"),
+});
+export const GENERATE_STRATEGIC_BRIEFING_ARGS_SCHEMA = z.object({
+    focusArea: z.string().optional(),
+});
+export const ANALYZE_CONSTITUTION_COMPLIANCE_ARGS_SCHEMA = z.object({
+    path: z.string().min(1),
+});
+export const GENERATE_DEPENDENCY_GRAPH_ARGS_SCHEMA = z.object({
+    path: z.string().default("src"),
+    format: z.enum(["mermaid", "json"]).default("mermaid"),
+});
+export const GENERATE_ACADEMY_PROGRESS_REPORT_ARGS_SCHEMA = z.object({
+    days: z.number().default(7),
+});
+export const ANALYZE_DOCUMENTATION_DEBT_ARGS_SCHEMA = z.object({
+    path: z.string().default("."),
+});
+export const VALIDATE_REPOSITORY_HEALTH_ARGS_SCHEMA = z.object({
+    scope: z.enum(["full", "lint", "test", "build"]).default("full"),
+});
+export const READ_AGENT_MESSAGES_ARGS_SCHEMA = z.object({
+    agent: z.string().min(1),
+});
+export const VERIFY_CONTRACT_INTEGRITY_ARGS_SCHEMA = z.object({
+    domain: z.string().min(1),
+});
+export const GENERATE_SEMANTIC_COMMIT_MESSAGE_ARGS_SCHEMA = z.object({
+    traceId: z.string().min(1),
+});
+export const ANALYZE_CODEBASE_INTELLIGENCE_ARGS_SCHEMA = z.object({
+    path: z.string().default("."),
+});
+export const GET_ACADEMY_PERFORMANCE_ARGS_SCHEMA = z.object({
+    periodDays: z.number().default(30),
+});
+export const ANALYZE_PROCEDURAL_CONTINUITY_ARGS_SCHEMA = z.object({
+    targetPath: z.string().min(1),
+    referencePath: z.string().min(1),
+});
+export const GET_AGENT_AUDIT_REPORT_ARGS_SCHEMA = z.object({
+    agent: z.string().min(1),
+    days: z.number().default(7),
+});

package/packages/framework-mcp/dist/tools/academy.js

@@ -0,0 +1,184 @@
+import fs from "fs";
+import path from "path";
+import { getFrameworkDir } from "../utils.js";
+import { GET_ACADEMY_PERFORMANCE_ARGS_SCHEMA, GENERATE_ACADEMY_PROGRESS_REPORT_ARGS_SCHEMA, GET_AGENT_AUDIT_REPORT_ARGS_SCHEMA, LOG_AGENT_ACTION_ARGS_SCHEMA } from "../schemas.js";
+export const academyTools = [
+    {
+        name: "get_academy_performance",
+        description: "Aggregates performance data from all agents to provide a global overview of the Academy's health and intelligence growth.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                periodDays: {
+                    type: "number",
+                    description: "Number of days to include in the report",
+                    default: 30,
+                },
+            },
+        },
+    },
+    {
+        name: "generate_strategic_briefing",
+        description: "Generates a high-level strategic briefing for the user, summarizing Academy health, progress, and future strategy.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                focusArea: {
+                    type: "string",
+                    description: "Optional area to focus on (e.g. 'quality', 'velocity', 'architecture')",
+                },
+            },
+        },
+    },
+    {
+        name: "generate_academy_progress_report",
+        description: "Generates a comprehensive narrative report on the Academy's progress, milestones, and challenges.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                days: {
+                    type: "number",
+                    description: "Number of days to include in the report",
+                    default: 7,
+                },
+            },
+        },
+    },
+    {
+        name: "get_agent_audit_report",
+        description: "Generates a summary report of an agent's activities based on their logs. Useful for self-improvement and progress tracking.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: {
+                    type: "string",
+                    description: "Agent name (e.g. analyst, backend)",
+                },
+                days: {
+                    type: "number",
+                    description: "Number of recent days to analyze",
+                    default: 7,
+                },
+            },
+            required: ["agent"],
+        },
+    },
+    {
+        name: "log_agent_action",
+        description: "Safely append a structured log entry to the agent's log file.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: { type: "string", description: "Agent name" },
+                action: { type: "string", description: "Action performed" },
+                requestId: { type: "string", description: "Trace ID or Request ID" },
+                files: { type: "array", items: { type: "string" }, description: "Files affected" },
+                status: { type: "string", enum: ["SUCCESS", "FAILURE"], description: "Action status" },
+                summary: { type: "string", description: "Short English summary" },
+                details: { type: "object", description: "Additional details" },
+            },
+            required: ["agent", "action", "requestId", "status", "summary"],
+        },
+    },
+];
+export const academyHandlers = {
+    get_academy_performance: async (args, projectRoot) => {
+        const parsed = GET_ACADEMY_PERFORMANCE_ARGS_SCHEMA.safeParse(args ?? {});
+        const days = parsed.success ? parsed.data.periodDays : 30;
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const logsDir = path.join(projectRoot, frameworkDir, "logs");
+            if (!fs.existsSync(logsDir))
+                return { content: [{ type: "text", text: "No logs found." }] };
+            const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+            let totalActions = 0, totalSuccess = 0;
+            const agentStats = fs.readdirSync(logsDir).filter(f => f.endsWith(".json")).map(file => {
+                const logs = JSON.parse(fs.readFileSync(path.join(logsDir, file), "utf-8")).filter((l) => new Date(l.timestamp) >= cutoff);
+                const success = logs.filter((l) => l.status === "SUCCESS").length;
+                totalActions += logs.length;
+                totalSuccess += success;
+                return { agent: file.replace(".json", ""), actions: logs.length, successRate: (success / (logs.length || 1)) * 100 };
+            }).filter(s => s.actions > 0);
+            return { content: [{ type: "text", text: `### GLOBAL ACADEMY PERFORMANCE REPORT\n\n- **Analysis Period:** Last ${days} days\n- **Global Success Rate:** ${((totalSuccess / (totalActions || 1)) * 100).toFixed(1)}%\n\n**Agent Breakdown:**\n` + agentStats.map(s => `- **@${s.agent}:** ${s.actions} actions (${s.successRate.toFixed(1)}% success)`).join("\n") }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Failed to generate global performance report." }] };
+        }
+    },
+    generate_strategic_briefing: async (args, projectRoot) => {
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const logsDir = path.join(projectRoot, frameworkDir, "logs");
+            let totalActions = 0, successCount = 0;
+            if (fs.existsSync(logsDir)) {
+                fs.readdirSync(logsDir).filter(f => f.endsWith(".json")).forEach(file => {
+                    const logs = JSON.parse(fs.readFileSync(path.join(logsDir, file), "utf-8"));
+                    totalActions += logs.length;
+                    successCount += logs.filter((l) => l.status === "SUCCESS").length;
+                });
+            }
+            const successRate = (successCount / (totalActions || 1)) * 100;
+            return { content: [{ type: "text", text: `# 🏛️ ACADEMY STRATEGIC BRIEFING\n\n- **Academy Health:** ${successRate.toFixed(1)}% Success Rate over ${totalActions} actions.\n**Status:** READY FOR PHASE_1 COMPLETION.` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Strategic briefing generation failed." }] };
+        }
+    },
+    generate_academy_progress_report: async (args, projectRoot) => {
+        const parsed = GENERATE_ACADEMY_PROGRESS_REPORT_ARGS_SCHEMA.safeParse(args ?? {});
+        const days = parsed.success ? parsed.data.days : 7;
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const memoryPath = path.join(projectRoot, frameworkDir, "PROJECT_MEMORY.md");
+            const memoryContent = fs.existsSync(memoryPath) ? fs.readFileSync(memoryPath, "utf-8") : "";
+            const historySection = memoryContent.match(/## HISTORY[\s\S]*$/m)?.[0] ?? "";
+            const milestones = Array.from(historySection.matchAll(/### (.*)\n\n- \*\*Agent:\*\* (.*)\n- \*\*Trace ID:\*\* (.*)\n- \*\*Action:\*\* (.*)/g)).slice(0, 5).map(m => `- [${m[1]}] **${m[2]}:** ${m[4]}`).join("\n");
+            return { content: [{ type: "text", text: `# 🎓 AGENT ACADEMY PROGRESS REPORT\n\n## 🏆 Key Milestones Achieved\n${milestones}` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Failed to generate progress report." }] };
+        }
+    },
+    get_agent_audit_report: async (args, projectRoot) => {
+        const parsed = GET_AGENT_AUDIT_REPORT_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success)
+            return { content: [{ type: "text", text: "Invalid agent or days argument." }] };
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const logPath = path.join(projectRoot, frameworkDir, "logs", `${parsed.data.agent}.json`);
+            if (!fs.existsSync(logPath))
+                return { content: [{ type: "text", text: `No logs found for agent: ${parsed.data.agent}` }] };
+            const cutoff = new Date(Date.now() - parsed.data.days * 24 * 60 * 60 * 1000);
+            const logs = JSON.parse(fs.readFileSync(logPath, "utf-8")).filter((l) => new Date(l.timestamp) >= cutoff);
+            const successCount = logs.filter((l) => l.status === "SUCCESS").length;
+            return { content: [{ type: "text", text: `### AGENT AUDIT REPORT: ${parsed.data.agent.toUpperCase()}\n\n- **Total Actions:** ${logs.length}\n- **Success Rate:** ${((successCount / (logs.length || 1)) * 100).toFixed(1)}%` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Failed to generate audit report." }] };
+        }
+    },
+    log_agent_action: async (args, projectRoot) => {
+        const parsed = LOG_AGENT_ACTION_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success)
+            return { content: [{ type: "text", text: "Invalid arguments for log_agent_action." }] };
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const logsDir = path.join(projectRoot, frameworkDir, "logs");
+            if (!fs.existsSync(logsDir))
+                fs.mkdirSync(logsDir, { recursive: true });
+            const logPath = path.join(logsDir, `${parsed.data.agent}.json`);
+            let logs = fs.existsSync(logPath) ? JSON.parse(fs.readFileSync(logPath, "utf-8")) : [];
+            if (!Array.isArray(logs))
+                logs = [];
+            const requestId = parsed.data.requestId;
+            if (requestId !== "—" && !/^[0-9A-Z]{26}$/.test(requestId))
+                return { content: [{ type: "text", text: "ERROR: requestId MUST be a 26-character ULID." }] };
+            logs.push({ timestamp: new Date().toISOString(), ...parsed.data });
+            fs.writeFileSync(logPath, JSON.stringify(logs, null, 2));
+            return { content: [{ type: "text", text: `SUCCESS: Logged action to ${parsed.data.agent}.json` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Failed to log action." }] };
+        }
+    },
+};

package/packages/framework-mcp/dist/tools/codebase.js

@@ -0,0 +1,294 @@
+import fs from "fs";
+import path from "path";
+import { Project } from "ts-morph";
+import { collectFilesRecursively, resolveSafePath } from "../utils.js";
+import { SEARCH_CODEBASE_ARGS_SCHEMA, ANALYZE_DEPENDENCIES_ARGS_SCHEMA, ANALYZE_CODEBASE_INTELLIGENCE_ARGS_SCHEMA, ANALYZE_PROCEDURAL_CONTINUITY_ARGS_SCHEMA, GENERATE_DEPENDENCY_GRAPH_ARGS_SCHEMA } from "../schemas.js";
+export const codebaseTools = [
+    {
+        name: "search_codebase",
+        description: "Semantic search across the codebase using grep for exact matches and context. Ideal for finding logic and patterns.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query or regex pattern",
+                },
+                extension: {
+                    type: "string",
+                    description: "File extension filter (e.g., ts, md)",
+                    default: "ts",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "codebase_search",
+        description: "Compatibility alias for search_codebase. Use when older agent prompts still reference codebase_search.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query or regex pattern",
+                },
+                extension: {
+                    type: "string",
+                    description: "File extension filter (e.g., ts, md)",
+                    default: "ts",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "analyze_dependencies",
+        description: "Analyze code dependencies for a specific file or folder using import tracking.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to analyze (relative to project root)",
+                },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "codebase_graph_query",
+        description: "Compatibility alias for analyze_dependencies. Returns import-level dependency information for a file or folder.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to analyze (relative to project root)",
+                },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "analyze_codebase_intelligence",
+        description: "Scans the codebase for complexity spikes and potential dead code (exported but unused symbols).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to scan (relative to project root)",
+                    default: ".",
+                },
+            },
+        },
+    },
+    {
+        name: "analyze_procedural_continuity",
+        description: "Compares a target file with a reference file to identify stylistic or structural deviations. Ensures agents follow existing patterns.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                targetPath: {
+                    type: "string",
+                    description: "Path to the newly created/modified file",
+                },
+                referencePath: {
+                    type: "string",
+                    description: "Path to an existing 'gold standard' file for comparison",
+                },
+            },
+            required: ["targetPath", "referencePath"],
+        },
+    },
+    {
+        name: "generate_dependency_graph",
+        description: "Generates a Mermaid-compatible dependency graph of the codebase or a specific directory.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to scan (relative to project root)",
+                    default: "src",
+                },
+                format: {
+                    type: "string",
+                    enum: ["mermaid", "json"],
+                    default: "mermaid",
+                },
+            },
+        },
+    },
+];
+export const codebaseHandlers = {
+    search_codebase: async (args, projectRoot) => {
+        const parsed = SEARCH_CODEBASE_ARGS_SCHEMA.safeParse(args);
+        if (!parsed.success) {
+            return { content: [{ type: "text", text: "Invalid query/extension argument." }] };
+        }
+        const { query, extension } = parsed.data;
+        try {
+            const files = collectFilesRecursively(projectRoot, new Set([extension]));
+            let queryRegex;
+            try {
+                queryRegex = new RegExp(query, "i");
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: "Invalid regex pattern in query." }] };
+            }
+            const matches = [];
+            const MAX_RESULTS = 30;
+            for (const filePath of files) {
+                if (matches.length >= MAX_RESULTS)
+                    break;
+                const content = fs.readFileSync(filePath, "utf-8");
+                const lines = content.split("\n");
+                for (let i = 0; i < lines.length; i++) {
+                    if (matches.length >= MAX_RESULTS)
+                        break;
+                    const line = lines[i];
+                    if (queryRegex.test(line)) {
+                        const relativePath = path.relative(projectRoot, filePath);
+                        matches.push(`- ${relativePath}:${i + 1}: ${line.trim()}`);
+                    }
+                }
+            }
+            return { content: [{ type: "text", text: matches.join("\n") || "No matches found." }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Search failed." }] };
+        }
+    },
+    analyze_dependencies: async (args, projectRoot) => {
+        const parsed = ANALYZE_DEPENDENCIES_ARGS_SCHEMA.safeParse(args);
+        if (!parsed.success) {
+            return { content: [{ type: "text", text: "Invalid path argument." }] };
+        }
+        const targetPath = parsed.data.path;
+        try {
+            const fullPath = resolveSafePath(projectRoot, targetPath);
+            if (!fs.existsSync(fullPath))
+                return { content: [{ type: "text", text: `Path not found: ${targetPath}` }] };
+            const stats = fs.statSync(fullPath);
+            const tsProject = new Project({ compilerOptions: { allowJs: true } });
+            if (stats.isDirectory()) {
+                tsProject.addSourceFilesAtPaths(path.join(fullPath, "**/*.{ts,tsx,js,jsx}"));
+                const sourceFiles = tsProject.getSourceFiles();
+                return { content: [{ type: "text", text: `Directory contains ${sourceFiles.length} source files. Use a specific file path for deep dependency analysis.` }] };
+            }
+            else {
+                const sourceFile = tsProject.addSourceFileAtPath(fullPath);
+                const imports = sourceFile.getImportDeclarations();
+                const importDetails = imports.map((imp) => {
+                    const moduleSpecifier = imp.getModuleSpecifierValue();
+                    const source = imp.getModuleSpecifierSourceFile();
+                    const resolvedPath = source ? path.relative(projectRoot, source.getFilePath()) : "unresolved/external";
+                    return `- ${moduleSpecifier} (${resolvedPath})`;
+                });
+                return { content: [{ type: "text", text: `Dependencies for ${targetPath}:\n${importDetails.length > 0 ? importDetails.join("\n") : "No imports found."}` }] };
+            }
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Analysis failed: " + (error instanceof Error ? error.message : String(error)) }] };
+        }
+    },
+    analyze_codebase_intelligence: async (args, projectRoot) => {
+        const parsed = ANALYZE_CODEBASE_INTELLIGENCE_ARGS_SCHEMA.safeParse(args);
+        const targetPath = parsed.success ? parsed.data.path : ".";
+        try {
+            const safeTargetPath = resolveSafePath(projectRoot, targetPath);
+            if (!fs.existsSync(safeTargetPath))
+                return { content: [{ type: "text", text: "Target path not found." }] };
+            const tsProject = new Project({ compilerOptions: { allowJs: true } });
+            tsProject.addSourceFilesAtPaths(path.join(safeTargetPath, "**/*.{ts,tsx}"));
+            const complexitySpikes = [];
+            const potentialDeadCode = [];
+            for (const sourceFile of tsProject.getSourceFiles()) {
+                const relativePath = path.relative(projectRoot, sourceFile.getFilePath());
+                const lineCount = sourceFile.getEndLineNumber();
+                if (lineCount > 300)
+                    complexitySpikes.push(`${relativePath} (${lineCount} lines)`);
+                sourceFile.getExportedDeclarations().forEach((declarations, name) => {
+                    const isUsed = tsProject.getSourceFiles().some(sf => {
+                        if (sf === sourceFile)
+                            return false;
+                        return sf.getImportDeclarations().some(i => i.getModuleSpecifierValue().includes(sourceFile.getBaseNameWithoutExtension()) && i.getNamedImports().some(ni => ni.getName() === name));
+                    });
+                    if (!isUsed && !sourceFile.getFilePath().includes("index.ts") && !sourceFile.getFilePath().includes("shared-types")) {
+                        potentialDeadCode.push(`${relativePath} -> ${name}`);
+                    }
+                });
+            }
+            return { content: [{ type: "text", text: `### CODEBASE INTELLIGENCE REPORT\n\n**Complexity Spikes (>300 lines):**\n${complexitySpikes.length > 0 ? complexitySpikes.map(s => `- ${s}`).join("\n") : "- None detected"}\n\n**Potential Dead Code (Unused Exports):**\n${potentialDeadCode.length > 0 ? potentialDeadCode.map(d => `- ${d}`).join("\n") : "- None detected (within scanned scope)"}` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Intelligence scan failed." }] };
+        }
+    },
+    analyze_procedural_continuity: async (args, projectRoot) => {
+        const parsed = ANALYZE_PROCEDURAL_CONTINUITY_ARGS_SCHEMA.safeParse(args);
+        if (!parsed.success)
+            return { content: [{ type: "text", text: "Invalid targetPath or referencePath." }] };
+        try {
+            const targetFull = resolveSafePath(projectRoot, parsed.data.targetPath);
+            const referenceFull = resolveSafePath(projectRoot, parsed.data.referencePath);
+            if (!fs.existsSync(targetFull) || !fs.existsSync(referenceFull))
+                return { content: [{ type: "text", text: "One or both files not found." }] };
+            const tsProject = new Project({ compilerOptions: { allowJs: true } });
+            const targetFile = tsProject.addSourceFileAtPath(targetFull);
+            const referenceFile = tsProject.addSourceFileAtPath(referenceFull);
+            const deviations = [];
+            const targetImports = targetFile.getImportDeclarations().map(i => i.getModuleSpecifierValue());
+            const referenceImports = referenceFile.getImportDeclarations().map(i => i.getModuleSpecifierValue());
+            const missingImports = referenceImports.filter(i => !targetImports.includes(i) && !i.startsWith("."));
+            if (missingImports.length > 0)
+                deviations.push(`Missing standard imports found in reference: ${missingImports.join(", ")}`);
+            if (referenceFile.getClasses().length > 0 && targetFile.getClasses().length === 0)
+                deviations.push("Reference uses classes, but target does not.");
+            const targetFunctions = targetFile.getFunctions().map(f => f.getName());
+            const referenceFunctions = referenceFile.getFunctions().map(f => f.getName());
+            if (referenceFunctions.some(f => f?.startsWith("get")) && !targetFunctions.some(f => f?.startsWith("get")))
+                deviations.push("Reference uses 'get' prefix for functions, target does not.");
+            return { content: [{ type: "text", text: deviations.length > 0 ? `### PROCEDURAL CONTINUITY DEVIATIONS\n\n${deviations.map(d => `- ${d}`).join("\n")}` : "No major structural or stylistic deviations detected based on reference." }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Continuity analysis failed." }] };
+        }
+    },
+    generate_dependency_graph: async (args, projectRoot) => {
+        const parsed = GENERATE_DEPENDENCY_GRAPH_ARGS_SCHEMA.safeParse(args);
+        const targetPath = parsed.success ? parsed.data.path : "src";
+        const format = parsed.success ? parsed.data.format : "mermaid";
+        try {
+            const safeTargetPath = resolveSafePath(projectRoot, targetPath);
+            if (!fs.existsSync(safeTargetPath))
+                return { content: [{ type: "text", text: "Target path not found." }] };
+            const tsProject = new Project({ compilerOptions: { allowJs: true } });
+            tsProject.addSourceFilesAtPaths(path.join(safeTargetPath, "**/*.{ts,tsx}"));
+            const edges = [];
+            for (const sourceFile of tsProject.getSourceFiles()) {
+                const from = sourceFile.getBaseNameWithoutExtension();
+                sourceFile.getImportDeclarations().forEach(imp => {
+                    const moduleSpecifier = imp.getModuleSpecifierValue();
+                    if (moduleSpecifier.startsWith(".")) {
+                        const to = path.basename(moduleSpecifier, path.extname(moduleSpecifier));
+                        edges.push({ from, to });
+                    }
+                });
+            }
+            if (format === "json")
+                return { content: [{ type: "text", text: JSON.stringify(edges, null, 2) }] };
+            let mermaid = "graph TD\n";
+            const uniqueEdges = Array.from(new Set(edges.map(e => `${e.from} --> ${e.to}`)));
+            if (uniqueEdges.length === 0)
+                return { content: [{ type: "text", text: "No internal dependencies found in the scanned path." }] };
+            mermaid += uniqueEdges.join("\n");
+            return { content: [{ type: "text", text: `### VISUAL ARCHITECTURE MAP: ${targetPath}\n\n\`\`\`mermaid\n${mermaid}\n\`\`\`\n\n**Total Nodes:** ${new Set(edges.flatMap(e => [e.from, e.to])).size} | **Total Edges:** ${uniqueEdges.length}` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Dependency graph generation failed." }] };
+        }
+    },
+};

package/packages/framework-mcp/dist/tools/contract.js

@@ -0,0 +1,95 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { Project } from "ts-morph";
+import { getFrameworkDir, collectFilesRecursively } from "../utils.js";
+import { VERIFY_CONTRACT_INTEGRITY_ARGS_SCHEMA } from "../schemas.js";
+export const contractTools = [
+    {
+        name: "verify_api_contract",
+        description: "Verify if the shared-types match the stored contract hash in contract.version.json.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "update_contract_hash",
+        description: "Generate a new hash for shared-types and update contract.version.json.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "verify_contract_integrity",
+        description: "Deeply analyzes API documentation and shared types to ensure they are perfectly synchronized.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                domain: {
+                    type: "string",
+                    description: "The API domain to verify (e.g. 'auth', 'user')",
+                },
+            },
+            required: ["domain"],
+        },
+    },
+];
+export const contractHandlers = {
+    verify_api_contract: async (args, projectRoot) => {
+        try {
+            const sharedTypesDir = path.join(projectRoot, "packages/shared-types/src");
+            const contractJsonPath = path.join(projectRoot, "packages/shared-types/contract.version.json");
+            if (!fs.existsSync(sharedTypesDir) || !fs.existsSync(contractJsonPath))
+                return { content: [{ type: "text", text: "Missing shared-types directory or contract.version.json" }] };
+            const files = collectFilesRecursively(sharedTypesDir, new Set(["ts"])).sort();
+            const hash = crypto.createHash("sha256");
+            files.forEach(f => hash.update(fs.readFileSync(f)));
+            const currentHash = hash.digest("hex");
+            const storedHash = JSON.parse(fs.readFileSync(contractJsonPath, "utf-8")).contract_hash;
+            return { content: [{ type: "text", text: currentHash === storedHash ? "✅ MATCH: Contract is valid and synchronized." : `❌ MISMATCH: Current hash (${currentHash.slice(0, 8)}...) does not match stored hash (${storedHash.slice(0, 8)}...).` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Failed to verify contract." }] };
+        }
+    },
+    update_contract_hash: async (args, projectRoot) => {
+        try {
+            const sharedTypesDir = path.join(projectRoot, "packages/shared-types/src");
+            const contractJsonPath = path.join(projectRoot, "packages/shared-types/contract.version.json");
+            if (!fs.existsSync(sharedTypesDir))
+                return { content: [{ type: "text", text: "Missing shared-types directory" }] };
+            const files = collectFilesRecursively(sharedTypesDir, new Set(["ts"])).sort();
+            if (files.length === 0)
+                return { content: [{ type: "text", text: "⚠️ WARNING: No TypeScript files found in shared-types/src. Hash not updated." }] };
+            const hash = crypto.createHash("sha256");
+            files.forEach(f => hash.update(fs.readFileSync(f)));
+            const currentHash = hash.digest("hex");
+            const contractJson = fs.existsSync(contractJsonPath) ? JSON.parse(fs.readFileSync(contractJsonPath, "utf-8")) : {};
+            contractJson.contract_hash = currentHash;
+            contractJson.last_updated = new Date().toISOString();
+            fs.writeFileSync(contractJsonPath, JSON.stringify(contractJson, null, 2));
+            return { content: [{ type: "text", text: `SUCCESS: Contract hash updated to ${currentHash}` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Failed to update contract hash." }] };
+        }
+    },
+    verify_contract_integrity: async (args, projectRoot) => {
+        const parsed = VERIFY_CONTRACT_INTEGRITY_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success)
+            return { content: [{ type: "text", text: "Invalid domain argument." }] };
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const apiDocPath = path.join(projectRoot, frameworkDir, "docs/api", `${parsed.data.domain}.md`);
+            const sharedTypesPath = path.join(projectRoot, "packages/shared-types/src/index.ts");
+            if (!fs.existsSync(apiDocPath))
+                return { content: [{ type: "text", text: `API documentation not found for domain: ${parsed.data.domain}` }] };
+            if (!fs.existsSync(sharedTypesPath))
+                return { content: [{ type: "text", text: "Shared types index.ts not found." }] };
+            const sourceFile = new Project().addSourceFileAtPath(sharedTypesPath);
+            const mentionedTypes = Array.from(fs.readFileSync(apiDocPath, "utf-8").matchAll(/`([^`]+)`/g)).map(m => m[1]).filter(t => /^[A-Z][a-zA-Z0-9]+(DTO|Response|Request|Status|Type)?$/.test(t));
+            const uniqueTypes = Array.from(new Set(mentionedTypes));
+            const missingTypes = uniqueTypes.filter(t => !sourceFile.getInterface(t) && !sourceFile.getTypeAlias(t) && !sourceFile.getEnum(t) && !sourceFile.getClass(t));
+            return { content: [{ type: "text", text: `### CONTRACT INTEGRITY SHIELD: ${parsed.data.domain.toUpperCase()}\n\n` + `- **Missing/Undefined Types:** ${missingTypes.length > 0 ? `⚠️ ${missingTypes.join(", ")}` : "✅ All types synchronized"}\n\n` + `**Result:** ${missingTypes.length === 0 ? "PASSED" : "FAILED"}` }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: "Contract verification failed." }] };
+        }
+    },
+};