@vfarcic/dot-ai 0.4.9 → 0.5.1

package/CLAUDE.md

@@ -0,0 +1,162 @@
+# DevOps AI Toolkit Project - Claude Code Integration Guide
+
+## ⚠️ MANDATORY TASK COMPLETION CHECKLIST ⚠️
+
+**🔴 BEFORE MARKING ANY TASK/SUBTASK AS COMPLETE:**
+
+□ **Tests Written**: Write tests for new functionality (can be after implementation)
+□ **All Tests Pass**: Run `npm test` - ALL 562+ tests must pass  
+□ **No Test Failures**: Fix any failing tests before proceeding
+□ **CLAUDE.md Updated**: Update this file if new features/commands/structure added
+
+**❌ TASK IS NOT COMPLETE IF:**
+- Any tests are failing
+- New code lacks test coverage  
+- You haven't run `npm test` to verify
+
+## PERMANENT INSTRUCTIONS
+
+**CRITICAL DEVELOPMENT RULES - NEVER OVERRIDE:**
+
+1. **Always Write Tests**: When making code changes, you MUST write or update tests to validate the changes
+2. **Always Run All Tests**: Before marking any task as complete, run `npm test` to ensure all tests pass  
+3. **Never Claim Done with Failing Tests**: A task is NOT complete if any tests are failing - fix all test failures first
+4. **Test-Driven Validation**: Changes are only considered successful when validated by passing tests
+5. **Always Update CLAUDE.md**: After finishing any task, check if CLAUDE.md needs updates to reflect new features, commands, structure changes, or documentation
+
+## 🛑 TESTING REMINDERS
+
+- **Current test suite**: 562+ tests across 21 suites - maintain this standard
+- **Implementation flow**: Code → Tests → `npm test` → Mark complete
+- **Pattern matching**: Look at `tests/schema.test.ts`, `tests/cli.test.ts` for testing patterns
+- **Test organization**: Mirror source code structure - tests should be organized using the same naming convention as the code they're testing
+  - `src/core/schema.ts` → `tests/core/schema.test.ts`
+  - `src/interfaces/cli.ts` → `tests/interfaces/cli.test.ts`
+  - `src/mcp/server.ts` → `tests/mcp/server.test.ts`
+  - Keep integration tests separate in `tests/integration/`
+
+## Project Overview
+
+**DevOps AI Toolkit** is an intelligent Kubernetes application deployment agent that discovers cluster capabilities and provides AI-powered recommendations for deploying applications using available resources.
+
+### Core Features
+- **Cluster Discovery**: Automatically discovers Kubernetes resources and custom operators
+- **AI Recommendations**: Get intelligent deployment recommendations based on your intent
+- **Solution Enhancement**: Process open-ended user requirements to enhance configurations
+- **Operator Integration**: Leverages custom operators like Crossplane, ArgoCD when available
+
+### Key Commands
+
+```bash
+# Core dot-ai commands
+dot-ai discover                           # Discover cluster resources
+dot-ai recommend --intent "description"   # Get AI-powered recommendations  
+dot-ai enhance --solution solution.json   # Enhance solutions with user requirements
+dot-ai explain Pod                        # Get detailed resource schema
+dot-ai fingerprint                        # Analyze cluster capabilities
+
+# Development commands
+npm test                                            # Run all tests
+npm run build                                       # Build the project
+npm run mcp:start                                   # Start MCP server
+```
+
+## AI Prompt Management 🤖
+
+**CRITICAL DEVELOPMENT RULE: NEVER hard-code AI prompts in source code**
+
+All AI prompts are stored as markdown files in the `prompts/` directory and loaded dynamically:
+
+### Prompt File Structure
+```
+prompts/
+├── intent-validation.md        # Validates user intent specificity
+├── resource-selection.md       # AI resource candidate selection
+├── resource-solution-ranking.md # AI resource ranking/scoring
+├── question-generation.md      # Generate configuration questions
+├── solution-enhancement.md     # Enhance solutions with requirements
+├── resource-analysis.md        # Analyze resource capabilities
+└── tool-instructions/          # Agent instructions for tools
+    ├── recommend.md           # User interaction requirements
+    ├── enhance-solution.md    # Enhancement tool instructions
+    └── recommendation-workflow.md # Workflow instructions
+```
+
+### Loading Pattern (ALWAYS USE THIS)
+```typescript
+// Load prompt template from file
+const fs = await import('fs');
+const path = await import('path');
+
+const promptPath = path.join(process.cwd(), 'prompts', 'your-prompt.md');
+const template = fs.readFileSync(promptPath, 'utf8');
+
+// Replace template variables
+const finalPrompt = template
+  .replace('{variable1}', value1)
+  .replace('{variable2}', value2);
+
+// Send to AI
+const response = await claudeIntegration.sendMessage(finalPrompt);
+```
+
+### Template Variables
+- Use `{variableName}` format in markdown files
+- Replace with `.replace('{variableName}', actualValue)`
+- Keep prompts readable and maintainable
+
+### Why File-Based Prompts?
+- **Version control**: Track prompt changes in git
+- **Collaboration**: Non-technical team members can edit prompts  
+- **Testing**: Easy to test different prompt variations
+- **Maintainability**: Separate concerns (logic vs. prompts)
+- **Consistency**: Standardized approach across all AI features
+
+### Adding New AI Features
+1. **Create prompt file**: `prompts/your-feature.md`
+2. **Use template variables**: `{intent}`, `{context}`, etc.
+3. **Load in code**: Follow the standard loading pattern above
+4. **Never hardcode**: Always load from file system
+
+### Project Structure
+
+```
+src/
+├── core/
+│   ├── discovery.ts      # Cluster discovery engine
+│   ├── schema.ts         # Resource schema parsing & AI recommendations
+│   ├── claude.ts         # Claude AI integration
+│   └── ...
+├── interfaces/
+│   ├── cli.ts           # CLI interface
+│   └── mcp.ts           # MCP server interface
+└── ...
+
+docs/                    # All documentation
+tests/                   # Comprehensive test suite (349+ tests)
+prompts/                 # AI prompt templates
+```
+
+### Testing & Development
+
+**MANDATORY TESTING WORKFLOW:**
+- **Always write tests** for code changes before considering work complete
+- **Always run all tests** with `npm test` before marking tasks as done
+- **Never mark task complete** if any tests are failing
+- **Always check CLAUDE.md** after task completion for needed updates
+
+**Commands:**
+- **Run tests**: `npm test` (351+ tests across 10 suites)
+- **Build**: `npm run build`
+- **Manual testing**: Follow examples in CLI and MCP guides
+- **Documentation**: See `docs/` directory for complete guides
+
+### Environment Setup
+
+```bash
+# Required for AI features
+export ANTHROPIC_API_KEY=your_api_key_here
+
+# Optional: Custom kubeconfig
+export KUBECONFIG=/path/to/kubeconfig.yaml
+```

package/bin/dot-ai.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { DotAI } from '../dist/core/index.js';
+import { CliInterface } from '../dist/interfaces/cli.js';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * CLI Binary Entry Point
+ * 
+ * Sets up the DevOps AI Toolkit and CLI interface for command line usage
+ */
+
+async function main() {
+  try {
+    // Parse kubeconfig option early for DotAI initialization
+    const kubeconfigIndex = process.argv.indexOf('--kubeconfig');
+    let kubeconfigPath: string | undefined;
+    
+    if (kubeconfigIndex !== -1 && kubeconfigIndex + 1 < process.argv.length) {
+      kubeconfigPath = process.argv[kubeconfigIndex + 1];
+    }
+
+    // Initialize the DevOps AI Toolkit with kubeconfig if provided
+    const dotAI = new DotAI(kubeconfigPath ? { kubernetesConfig: kubeconfigPath } : {});
+    await dotAI.initialize();
+
+    // Create CLI interface
+    const cli = new CliInterface(dotAI);
+
+    // Run CLI with full process.argv (commander.js handles parsing)
+    await cli.run(process.argv);
+  } catch (error) {
+    console.error('Fatal error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// Run if this module is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { main }; 

package/destroy.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+
+# destroy.sh - Cleanup script for DevOps AI Toolkit Kubernetes cluster
+# This script destroys the kind cluster and cleans up resources created by setup.sh
+
+set -e  # Exit on any error
+
+KUBECONFIG_PATH="$PWD/kubeconfig.yaml"
+CLUSTER_NAME="dot-ai-test"
+
+echo "🧹 Destroying DevOps AI Toolkit Kubernetes cluster..."
+
+# Check if kind is available
+if ! command -v kind &> /dev/null; then
+    echo "❌ Error: kind is not installed"
+    echo "Cannot destroy cluster without kind CLI tool"
+    exit 1
+fi
+
+# Delete the kind cluster
+echo "🗑️  Deleting kind cluster '$CLUSTER_NAME'..."
+if kind get clusters | grep -q "^$CLUSTER_NAME$"; then
+    kind delete cluster --name "$CLUSTER_NAME"
+    echo "✅ Cluster '$CLUSTER_NAME' deleted successfully"
+else
+    echo "ℹ️  Cluster '$CLUSTER_NAME' not found (may already be deleted)"
+fi
+
+# Remove kubeconfig file
+if [ -f "$KUBECONFIG_PATH" ]; then
+    echo "🗑️  Removing kubeconfig file..."
+    rm -f "$KUBECONFIG_PATH"
+    echo "✅ Kubeconfig file '$KUBECONFIG_PATH' removed"
+else
+    echo "ℹ️  Kubeconfig file '$KUBECONFIG_PATH' not found"
+fi
+
+# Clean up any helm repositories that were added (optional cleanup)
+echo "🧹 Cleaning up helm repositories..."
+helm repo remove crossplane-stable 2>/dev/null || echo "ℹ️  crossplane-stable repo not found"
+helm repo remove crossplane-preview 2>/dev/null || echo "ℹ️  crossplane-preview repo not found"
+
+echo "🎉 Cleanup complete!"
+echo "💡 If you had KUBECONFIG exported, you may want to unset it:"
+echo "   unset KUBECONFIG"

package/devbox.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.14.2/.schema/devbox.schema.json",
+  "packages": [
+    "kind@0.29.0",
+    "git@2.49.0",
+    "teller@2.0.7",
+    "kubernetes-helm@3.18.3"
+  ],
+  "shell": {
+    "init_hook": [],
+    "scripts":   {}
+  }
+}

package/devbox.lock

@@ -0,0 +1,225 @@
+{
+  "lockfile_version": "1",
+  "packages": {
+    "git@2.49.0": {
+      "last_modified": "2025-06-20T02:24:11Z",
+      "resolved": "github:NixOS/nixpkgs/076e8c6678d8c54204abcb4b1b14c366835a58bb#git",
+      "source": "devbox-search",
+      "version": "2.49.0",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/ir2bhb7n3ngh0dg7p6jbhm1wa4d8gkb7-git-2.49.0",
+              "default": true
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/f0bi1v08ki7pq6a4rzhjhnp5szj3940k-git-2.49.0-doc"
+            }
+          ],
+          "store_path": "/nix/store/ir2bhb7n3ngh0dg7p6jbhm1wa4d8gkb7-git-2.49.0"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/5p8ljxbgnk31zxbz8hvrfkg1qfgiv3qi-git-2.49.0",
+              "default": true
+            },
+            {
+              "name": "debug",
+              "path": "/nix/store/isw51rw1b78yw6k454m7h402k88n291w-git-2.49.0-debug"
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/hxw5vli42579b8bkxv6nq2p2z4vjvw97-git-2.49.0-doc"
+            }
+          ],
+          "store_path": "/nix/store/5p8ljxbgnk31zxbz8hvrfkg1qfgiv3qi-git-2.49.0"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/72qfjivfnm6kzdfbiavvici8bi3jzrs6-git-2.49.0",
+              "default": true
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/900nidzjyaa0950wk104vzgb82h5wspi-git-2.49.0-doc"
+            }
+          ],
+          "store_path": "/nix/store/72qfjivfnm6kzdfbiavvici8bi3jzrs6-git-2.49.0"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/rzqvhv48m3nh8g3j4k6jmz6yqy8apr95-git-2.49.0",
+              "default": true
+            },
+            {
+              "name": "debug",
+              "path": "/nix/store/201xjz2py285323n3y7r30frdwbdnb6q-git-2.49.0-debug"
+            },
+            {
+              "name": "doc",
+              "path": "/nix/store/zcjdp82yx46w8yp1inxkkzb3a3k05a0m-git-2.49.0-doc"
+            }
+          ],
+          "store_path": "/nix/store/rzqvhv48m3nh8g3j4k6jmz6yqy8apr95-git-2.49.0"
+        }
+      }
+    },
+    "github:NixOS/nixpkgs/nixpkgs-unstable": {
+      "last_modified": "2025-06-01T15:36:18Z",
+      "resolved": "github:NixOS/nixpkgs/5929de975bcf4c7c8d8b5ca65c8cd9ef9e44523e?lastModified=1748792178&narHash=sha256-BHmgfHlCJVNisJShVaEmfDIr%2FIp58i%2F4oFGlD1iK6lk%3D"
+    },
+    "kind@0.29.0": {
+      "last_modified": "2025-06-20T02:24:11Z",
+      "resolved": "github:NixOS/nixpkgs/076e8c6678d8c54204abcb4b1b14c366835a58bb#kind",
+      "source": "devbox-search",
+      "version": "0.29.0",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/ndl4z2y9nsn7n5ii7hs49ddg79p2pb6a-kind-0.29.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/ndl4z2y9nsn7n5ii7hs49ddg79p2pb6a-kind-0.29.0"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/j9sdb4vkf9ck1kvfy8vvn17cq3a21s6a-kind-0.29.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/j9sdb4vkf9ck1kvfy8vvn17cq3a21s6a-kind-0.29.0"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/161h1s9n2260g2lr3dsjmfczv8gjx5q9-kind-0.29.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/161h1s9n2260g2lr3dsjmfczv8gjx5q9-kind-0.29.0"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/swafyrx3qn2xjdz3sp7dy8pg7bxpfn3h-kind-0.29.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/swafyrx3qn2xjdz3sp7dy8pg7bxpfn3h-kind-0.29.0"
+        }
+      }
+    },
+    "kubernetes-helm@3.18.3": {
+      "last_modified": "2025-06-22T15:15:55Z",
+      "resolved": "github:NixOS/nixpkgs/3078b9a9e75f1790e6d6ef9955fdc6a2d1740cc6#kubernetes-helm",
+      "source": "devbox-search",
+      "version": "3.18.3",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/pq4scdg2cz3pxv1v8l89xsbx5ca7i48d-kubernetes-helm-3.18.3",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/pq4scdg2cz3pxv1v8l89xsbx5ca7i48d-kubernetes-helm-3.18.3"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/v4p0yq3dc21dhh8mlws3dwlqqk74a4f8-kubernetes-helm-3.18.3",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/v4p0yq3dc21dhh8mlws3dwlqqk74a4f8-kubernetes-helm-3.18.3"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/6000mdd9sz6yqax9wd2qz451qj13bmip-kubernetes-helm-3.18.3",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/6000mdd9sz6yqax9wd2qz451qj13bmip-kubernetes-helm-3.18.3"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/r1r9fz9nf0yniwqc2b51zi36cz4d7ala-kubernetes-helm-3.18.3",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/r1r9fz9nf0yniwqc2b51zi36cz4d7ala-kubernetes-helm-3.18.3"
+        }
+      }
+    },
+    "teller@2.0.7": {
+      "last_modified": "2025-06-20T02:24:11Z",
+      "resolved": "github:NixOS/nixpkgs/076e8c6678d8c54204abcb4b1b14c366835a58bb#teller",
+      "source": "devbox-search",
+      "version": "2.0.7",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/7ri6fgskrzxxkzvxrqiarbica997zzlp-teller-2.0.7",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/7ri6fgskrzxxkzvxrqiarbica997zzlp-teller-2.0.7"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/rzakhwmvhxf62aarw25281qrzpkvjqvw-teller-2.0.7",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/rzakhwmvhxf62aarw25281qrzpkvjqvw-teller-2.0.7"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/7n5i7rd8fdiv4kbfnbj44q6fc7m4sqic-teller-2.0.7",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/7n5i7rd8fdiv4kbfnbj44q6fc7m4sqic-teller-2.0.7"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/25pl4iwnnv16dbdb6yir78p9ahjfj987-teller-2.0.7",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/25pl4iwnnv16dbdb6yir78p9ahjfj987-teller-2.0.7"
+        }
+      }
+    }
+  }
+}