@vfarcic/dot-ai 0.1.0

package/dist/tools/recommend.js

@@ -0,0 +1,332 @@
+"use strict";
+/**
+ * Recommend Tool - AI-powered Kubernetes resource recommendations
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOMMEND_TOOL_INPUT_SCHEMA = exports.RECOMMEND_TOOL_DESCRIPTION = exports.RECOMMEND_TOOL_NAME = void 0;
+exports.handleRecommendTool = handleRecommendTool;
+const zod_1 = require("zod");
+const error_handling_1 = require("../core/error-handling");
+const schema_1 = require("../core/schema");
+const claude_1 = require("../core/claude");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const session_utils_1 = require("../core/session-utils");
+// Tool metadata for direct MCP registration
+exports.RECOMMEND_TOOL_NAME = 'recommend';
+exports.RECOMMEND_TOOL_DESCRIPTION = 'Deploy, create, run, or setup applications on Kubernetes with AI-powered recommendations. Ask the user to describe their application first, then use their response here.';
+// Zod schema for MCP registration
+exports.RECOMMEND_TOOL_INPUT_SCHEMA = {
+    intent: zod_1.z.string().min(1).max(1000).describe('What the user wants to deploy, create, run, or setup on Kubernetes (based on their description). Ask the user to describe their application first, then use their response here. Examples: "deploy a web application", "create a database cluster", "run my Node.js API", "setup a Redis cache", "launch a microservice", "build a CI/CD pipeline", "deploy a WordPress site", "create a monitoring stack", "run a Python Flask app", "setup MongoDB", "deploy a React frontend", "create a load balancer"')
+};
+/**
+ * Validate intent meaningfulness using AI
+ */
+async function validateIntentWithAI(intent, claudeIntegration) {
+    try {
+        // Load prompt template
+        const promptPath = path.join(process.cwd(), 'prompts', 'intent-validation.md');
+        const template = fs.readFileSync(promptPath, 'utf8');
+        // Replace template variables
+        const validationPrompt = template.replace('{intent}', intent);
+        // Send to Claude for validation
+        const response = await claudeIntegration.sendMessage(validationPrompt);
+        // Parse JSON response with robust error handling
+        let jsonContent = response.content;
+        // Try to find JSON object wrapped in code blocks
+        const codeBlockMatch = response.content.match(/```(?:json)?\s*(\{[\s\S]*?\})\s*```/);
+        if (codeBlockMatch) {
+            jsonContent = codeBlockMatch[1];
+        }
+        else {
+            // Try to find JSON object that starts with { and find the matching closing }
+            const startIndex = response.content.indexOf('{');
+            if (startIndex !== -1) {
+                let braceCount = 0;
+                let endIndex = startIndex;
+                for (let i = startIndex; i < response.content.length; i++) {
+                    if (response.content[i] === '{')
+                        braceCount++;
+                    if (response.content[i] === '}')
+                        braceCount--;
+                    if (braceCount === 0) {
+                        endIndex = i;
+                        break;
+                    }
+                }
+                if (braceCount === 0) {
+                    jsonContent = response.content.substring(startIndex, endIndex + 1);
+                }
+            }
+        }
+        const validation = JSON.parse(jsonContent.trim());
+        // Validate response structure
+        if (typeof validation.isSpecific !== 'boolean' ||
+            typeof validation.reason !== 'string' ||
+            !Array.isArray(validation.suggestions)) {
+            throw new Error('AI response has invalid structure');
+        }
+        // If intent is not specific enough, throw error with suggestions
+        if (!validation.isSpecific) {
+            const suggestions = validation.suggestions.length
+                ? validation.suggestions.map((s) => `• ${s}`).join('\n')
+                : '• Include specific technology (Node.js, PostgreSQL, React, etc.)\n• Describe the purpose or function\n• Add context about requirements';
+            throw new Error(`Intent needs more specificity: ${validation.reason}\n\n` +
+                `Suggestions to improve your intent:\n${suggestions}\n\n` +
+                `Original intent: "${intent}"`);
+        }
+    }
+    catch (error) {
+        // If it's our validation error, re-throw it
+        if (error instanceof Error && error.message.includes('Intent needs more specificity')) {
+            throw error;
+        }
+        // For other errors (AI service issues, JSON parsing, etc.), 
+        // continue without blocking the user - log the issue but don't fail
+        console.warn('Intent validation failed, continuing with original intent:', error);
+        return;
+    }
+}
+/**
+ * Generate unique solution ID with timestamp and random component
+ */
+function generateSolutionId() {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '').split('T');
+    const dateTime = timestamp[0] + 'T' + timestamp[1].substring(0, 6);
+    const randomHex = crypto.randomBytes(6).toString('hex');
+    return `sol_${dateTime}_${randomHex}`;
+}
+/**
+ * Write solution data to file atomically (temp file + rename)
+ */
+function writeSolutionFile(sessionDir, solutionId, solutionData) {
+    const fileName = `${solutionId}.json`;
+    const filePath = path.join(sessionDir, fileName);
+    const tempPath = filePath + '.tmp';
+    try {
+        // Write to temporary file first
+        fs.writeFileSync(tempPath, JSON.stringify(solutionData, null, 2));
+        // Atomically rename to final location
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        // Clean up temp file if it exists
+        try {
+            if (fs.existsSync(tempPath)) {
+                fs.unlinkSync(tempPath);
+            }
+        }
+        catch (cleanupError) {
+            // Ignore cleanup errors
+        }
+        throw new Error(`Failed to write solution file ${fileName}: ${error}`);
+    }
+}
+/**
+ * Direct MCP tool handler for recommend functionality
+ */
+async function handleRecommendTool(args, dotAI, logger, requestId) {
+    return await error_handling_1.ErrorHandler.withErrorHandling(async () => {
+        logger.debug('Handling recommend request', { requestId, intent: args?.intent });
+        // Input validation is handled automatically by MCP SDK with Zod schema
+        // args are already validated and typed when we reach this point
+        // Check for Claude API key
+        const claudeApiKey = dotAI.getAnthropicApiKey();
+        if (!claudeApiKey) {
+            throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.AI_SERVICE, error_handling_1.ErrorSeverity.HIGH, 'ANTHROPIC_API_KEY environment variable must be set for AI-powered resource recommendations', {
+                operation: 'api_key_check',
+                component: 'RecommendTool',
+                requestId,
+                suggestedActions: [
+                    'Set ANTHROPIC_API_KEY environment variable',
+                    'Verify the API key is valid and active',
+                    'Check that the API key has sufficient credits'
+                ]
+            });
+        }
+        // Validate session directory configuration
+        let sessionDir;
+        try {
+            sessionDir = (0, session_utils_1.getAndValidateSessionDirectory)(args, true); // requireWrite=true
+            logger.debug('Session directory validated', { requestId, sessionDir });
+        }
+        catch (error) {
+            throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.VALIDATION, error_handling_1.ErrorSeverity.HIGH, `Session directory validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`, {
+                operation: 'session_directory_validation',
+                component: 'RecommendTool',
+                requestId,
+                suggestedActions: [
+                    'Ensure session directory exists and is writable',
+                    'Set --session-dir parameter or DOT_AI_SESSION_DIR environment variable',
+                    'Check directory permissions'
+                ]
+            }, error instanceof Error ? error : new Error(String(error)));
+        }
+        logger.info('Starting resource recommendation process', {
+            requestId,
+            intent: args.intent,
+            hasApiKey: !!claudeApiKey
+        });
+        // Validate intent specificity with AI before expensive resource discovery
+        logger.debug('Validating intent specificity', { requestId, intent: args.intent });
+        try {
+            const claudeIntegration = new claude_1.ClaudeIntegration(claudeApiKey);
+            await validateIntentWithAI(args.intent, claudeIntegration);
+            logger.debug('Intent validation passed', { requestId });
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Intent needs more specificity')) {
+                // This is a validation error that should be returned to the user
+                throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.VALIDATION, error_handling_1.ErrorSeverity.MEDIUM, error.message, {
+                    operation: 'intent_validation',
+                    component: 'RecommendTool',
+                    requestId,
+                    input: { intent: args.intent },
+                    suggestedActions: [
+                        'Provide more specific details about your deployment',
+                        'Include technology stack information',
+                        'Describe the purpose or function of what you want to deploy'
+                    ]
+                }, error);
+            }
+            // For other errors, log but continue (don't block user due to AI service issues)
+            logger.warn('Intent validation failed, continuing with recommendation', { requestId, error: error instanceof Error ? error.message : 'Unknown error' });
+        }
+        // Initialize AI-powered ResourceRecommender
+        const rankingConfig = { claudeApiKey };
+        const recommender = new schema_1.ResourceRecommender(rankingConfig);
+        // Create discovery functions
+        const discoverResourcesFn = async () => {
+            logger.debug('Discovering cluster resources', { requestId });
+            return await dotAI.discovery.discoverResources();
+        };
+        const explainResourceFn = async (resource) => {
+            logger.debug(`Explaining resource: ${resource}`, { requestId });
+            return await dotAI.discovery.explainResource(resource);
+        };
+        // Find best solutions for the user intent
+        logger.debug('Generating recommendations with AI', { requestId });
+        const solutions = await recommender.findBestSolutions(args.intent, discoverResourcesFn, explainResourceFn);
+        logger.info('Recommendation process completed', {
+            requestId,
+            solutionCount: solutions.length,
+            topScore: solutions[0]?.score
+        });
+        // Create solution files and build response
+        const solutionSummaries = [];
+        const timestamp = new Date().toISOString();
+        // Limit to top 5 solutions (respecting quality thresholds from AI ranking)
+        const topSolutions = solutions.slice(0, 5);
+        for (const solution of topSolutions) {
+            const solutionId = generateSolutionId();
+            // Create complete solution file with all data
+            const solutionFileData = {
+                solutionId,
+                intent: args.intent,
+                type: solution.type,
+                score: solution.score,
+                description: solution.description,
+                reasons: solution.reasons,
+                analysis: solution.analysis,
+                resources: solution.resources.map(r => ({
+                    kind: r.kind,
+                    apiVersion: r.apiVersion,
+                    group: r.group,
+                    description: r.description
+                })),
+                questions: solution.questions,
+                answers: {}, // Empty initially - will be filled by answerQuestion tool
+                timestamp
+            };
+            // Write solution to file
+            try {
+                writeSolutionFile(sessionDir, solutionId, solutionFileData);
+                logger.debug('Solution file created', { requestId, solutionId, fileName: `${solutionId}.json` });
+            }
+            catch (error) {
+                throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.STORAGE, error_handling_1.ErrorSeverity.HIGH, `Failed to store solution file: ${error instanceof Error ? error.message : 'Unknown error'}`, {
+                    operation: 'solution_file_creation',
+                    component: 'RecommendTool',
+                    requestId,
+                    input: { solutionId },
+                    suggestedActions: [
+                        'Check session directory write permissions',
+                        'Ensure sufficient disk space',
+                        'Verify session directory is accessible'
+                    ]
+                }, error instanceof Error ? error : new Error(String(error)));
+            }
+            // Add to response summary (decision-making data only)
+            solutionSummaries.push({
+                solutionId,
+                type: solution.type,
+                score: solution.score,
+                description: solution.description,
+                primaryResources: solution.resources.slice(0, 3).map(r => r.kind),
+                reasons: solution.reasons,
+                analysis: solution.analysis
+            });
+        }
+        // Build new response format
+        const response = {
+            intent: args.intent,
+            solutions: solutionSummaries,
+            nextAction: "Call chooseSolution with your preferred solutionId",
+            guidance: "🛑 NEVER choose automatically - Present ALL solutions to user and ask them to choose by calling chooseSolution(solutionId)",
+            timestamp
+        };
+        logger.info('Solution files created and response prepared', {
+            requestId,
+            solutionCount: solutionSummaries.length,
+            sessionDir
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(response, null, 2)
+                }]
+        };
+    }, {
+        operation: 'recommend_tool',
+        component: 'RecommendTool',
+        requestId,
+        input: args
+    }, {
+        convertToMcp: true,
+        retryCount: 1
+    });
+}

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@vfarcic/dot-ai",
+  "version": "0.1.0",
+  "description": "Universal Kubernetes application deployment agent with CLI and MCP interfaces",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "dot-ai": "./dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./mcp": "./dist/mcp/server.js"
+  },
+  "scripts": {
+    "pretest": "npm run build",
+    "test": "jest --silent",
+    "test:verbose": "jest --verbose",
+    "test:watch": "jest --watch --silent",
+    "test:coverage": "jest --coverage --silent",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean && npm run lint",
+    "build": "tsc --sourceMap false",
+    "build:prod": "npm run clean && tsc --sourceMap false --removeComments true",
+    "build:dev": "tsc --sourceMap true",
+    "build:watch": "tsc --watch",
+    "build:cli": "npm run build && chmod +x dist/cli.js",
+    "build:mcp": "npm run build && echo 'MCP server built successfully'",
+    "dev": "ts-node src/index.ts",
+    "start:cli": "node dist/cli.js",
+    "start:mcp": "node dist/mcp/server.js",
+    "lint": "eslint src/ --ext .ts",
+    "format": "prettier --write src/",
+    "ci": "npm run lint && npm run ci:build && npm run ci:test && npm run ci:security",
+    "ci:test": "npm run test",
+    "ci:build": "npm run build:prod",
+    "ci:security": "npm audit --audit-level moderate",
+    "audit": "npm audit",
+    "version:dev": "npm version patch --preid=devel --prerelease",
+    "version:prod": "npm version patch"
+  },
+  "keywords": [
+    "kubernetes",
+    "deployment",
+    "cli",
+    "mcp",
+    "devops",
+    "containers",
+    "ai",
+    "automation",
+    "cloud-native"
+  ],
+  "author": "Viktor Farcic",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vfarcic/dot-ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vfarcic/dot-ai/issues"
+  },
+  "homepage": "https://github.com/vfarcic/dot-ai#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.27.0",
+    "@kubernetes/client-node": "^1.3.0",
+    "@modelcontextprotocol/sdk": "^1.13.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^11.1.0",
+    "yaml": "^2.8.0"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "silent": false,
+    "verbose": false,
+    "roots": [
+      "<rootDir>/src",
+      "<rootDir>/tests"
+    ],
+    "testMatch": [
+      "**/__tests__/**/*.ts",
+      "**/*.test.ts",
+      "**/*.spec.ts"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/**/*.d.ts",
+      "!src/**/index.ts"
+    ],
+    "coverageDirectory": "coverage",
+    "coverageReporters": [
+      "text",
+      "lcov",
+      "html"
+    ],
+    "moduleNameMapper": {
+      "@kubernetes/client-node": "<rootDir>/tests/__mocks__/@kubernetes/client-node.ts"
+    },
+    "setupFilesAfterEnv": ["<rootDir>/tests/setup.ts"]
+  }
+}

package/prompts/intent-validation.md

@@ -0,0 +1,65 @@
+# Intent Validation for Kubernetes Deployment Recommendations
+
+You are a Kubernetes expert analyzing user intents for deployment recommendations. Evaluate whether this intent provides enough specificity to generate meaningful Kubernetes deployment recommendations.
+
+## User Intent
+{intent}
+
+## Evaluation Criteria
+
+An intent is **TOO VAGUE OR GENERIC** if it:
+- Completely generic terms without context (e.g., just "app", "something", "service" alone)
+- Single action words without objects (e.g., "deploy", "create", "setup", "run" alone)
+- Meaningless requests (e.g., "help", "please", "can you")
+- Extremely short without any technical context (1-2 words like "database", "container")
+
+An intent is **SPECIFIC ENOUGH** if it includes ANY of:
+- Specific technology or framework (Node.js, PostgreSQL, Redis, React, Python, etc.)
+- Clear architectural pattern (stateless app, microservice, web server, REST API, etc.)
+- Application type or purpose (frontend, backend, database, cache, queue, etc.)
+- Deployment context that helps understand Kubernetes resource needs
+
+**IMPORTANT**: Be generous in accepting intents. Focus on rejecting only truly meaningless requests. Terms like "stateless app", "web application", "microservice", "database cluster" provide sufficient Kubernetes deployment context.
+
+## Examples
+
+**TOO VAGUE:**
+- "create an app" (no architectural or technical context)
+- "deploy something" (completely generic)
+- "database" (single word, no context)
+- "help" (not a deployment request)
+- "app" (single word)
+- "setup" (action without object)
+
+**SPECIFIC ENOUGH:**
+- "stateless app" (architectural pattern + type)
+- "web application" (clear application type)
+- "microservice" (architectural pattern)
+- "REST API" (clear service type)
+- "database cluster" (type + deployment pattern)
+- "Node.js application" (technology + type)
+- "frontend service" (purpose + type)
+- "cache service" (purpose + type)
+
+## Response Format
+
+Respond with ONLY a JSON object in this exact format:
+
+```json
+{
+  "isSpecific": boolean,
+  "reason": "brief explanation of why it is or isn't specific enough",
+  "suggestions": [
+    "specific suggestion 1 to improve the intent",
+    "specific suggestion 2 to improve the intent", 
+    "specific suggestion 3 to improve the intent"
+  ]
+}
+```
+
+**IMPORTANT:** 
+- Your response must be ONLY the JSON object, nothing else
+- If `isSpecific` is true, still provide 3 suggestions for making it even more detailed
+- If `isSpecific` is false, provide 3 concrete suggestions to make it deployable
+- Keep suggestions practical and actionable
+- Focus on what technologies, purposes, or contexts are missing

package/prompts/manifest-generation.md

@@ -0,0 +1,79 @@
+# Kubernetes Manifest Generation
+
+## Solution Configuration
+{solution}
+
+## Resource Schemas
+The following schemas are available for the resources selected in the solution:
+{schemas}
+
+## Previous Attempt (if retry)
+{previous_attempt}
+
+## Validation Error Details (if retry)
+{error_details}
+
+## Instructions
+
+Generate production-ready Kubernetes YAML manifests from the complete solution configuration. The solution contains all necessary context including discovered resource schemas, user answers, cluster capabilities, and selected resource types.
+
+### Core Strategy:
+
+1. **Analyze Solution Data**:
+   - Use the selected resource types from the solution
+   - Review discovered resource schemas and cluster capabilities
+   - Understand the complete context of what's available
+
+2. **Apply User Configuration**:
+   - Map all question answers to appropriate manifest fields
+   - **CRITICAL**: Use ONLY the fields defined in the provided resource schemas
+   - Do not invent or guess field names - refer to the schema section above
+   - Apply configuration values appropriately for the specific resource type
+
+3. **Cross-Resource Field Mapping**:
+   - Many user answers apply to multiple resources in the solution
+   - Use the same values consistently across related resources where appropriate
+   - Ensure proper relationships between resources through consistent naming and labeling
+   - Apply configuration values to all relevant fields across different resource types
+
+4. **Process Open Requirements**:
+   - If user provided open requirements, analyze their specific needs
+   - Use available cluster resources to fulfill those requirements intelligently
+   - Make enhancement decisions based on actual cluster capabilities
+   - **CRITICAL**: Add any additional resources needed to fulfill open requirements:
+     * **Hostname/Domain access** → Add Ingress resource with appropriate rules
+     * **External configuration** → Add ConfigMap resources
+     * **Secrets/credentials** → Add Secret resources
+     * **SSL/TLS requirements** → Add TLS configuration to Ingress
+     * **Persistent storage needs** → Add PersistentVolumeClaim resources
+     * **Network policies** → Add NetworkPolicy resources
+     * **Resource limits** → Add ResourceQuota or LimitRange resources
+
+5. **Generate Appropriate Manifests**:
+   - Create manifests for the selected resource types
+   - **IMPORTANT**: Include any additional supporting resources needed to fulfill open requirements
+   - Use correct API versions and schemas from the solution data
+   - Ensure all resources work together to meet user's complete requirements
+
+### For Retry Attempts:
+If this is a retry (previous attempt and error details provided above):
+- Analyze the previous manifests to understand what was generated
+- Study the validation error to identify the specific problem
+- Make targeted corrections to fix the identified issues
+- Preserve parts of the manifests that didn't cause validation errors
+
+### Response Requirements:
+
+1. **Use Solution Context**: Base all decisions on the provided solution data, not assumptions
+2. **Valid Manifests**: Generate syntactically correct YAML that passes Kubernetes validation
+3. **Complete Configuration**: Include all resources needed for deployment
+4. **Production Ready**: Follow Kubernetes best practices for the specific resource types
+5. **Error-Free**: If this is a retry, specifically address the validation errors
+
+## Response Format
+
+**CRITICAL**: Return ONLY valid YAML manifests. NO explanations, NO markdown blocks, NO additional text.
+
+Separate multiple resources with `---`.
+
+**RETURN ONLY THE YAML MANIFESTS**