@vfarcic/dot-ai 0.4.9 → 0.5.1

package/docs/API.md

@@ -0,0 +1,449 @@
+# API Reference
+
+## Programmatic Usage
+
+### Discovery Engine
+
+```typescript
+import { KubernetesDiscovery } from './src/core/discovery';
+
+const discovery = new KubernetesDiscovery({ 
+  kubeconfigPath: './kubeconfig.yaml' 
+});
+
+await discovery.connect();
+
+// Discover all available resources
+const resources = await discovery.getAPIResources();
+console.log(`Found ${resources.length} resources`);
+
+// Get cluster fingerprint
+const fingerprint = await discovery.fingerprintCluster();
+console.log(`Cluster: ${fingerprint.platform} v${fingerprint.version}`);
+
+// Analyze resource schema
+const podSchema = await discovery.explainResource('Pod');
+console.log(`Pod has ${podSchema.fields.length} fields`);
+```
+
+### AI-Powered Recommendations (Legacy - Use MCP Tools)
+
+**Note: Direct programmatic access is available but the recommended approach is via MCP tools for conversational workflows.**
+
+```typescript
+import { ResourceRecommender } from './src/core/schema';
+
+// Get AI-powered resource recommendations (legacy approach)
+const recommender = new ResourceRecommender({ claudeApiKey: 'your-key' });
+const solutions = await recommender.findBestSolutions(
+  'deploy a web application with scaling',
+  () => discovery.discoverResources(),
+  (resource) => discovery.explainResource(resource)
+);
+
+console.log(`Found ${solutions.length} solutions`);
+console.log(`Best solution: ${solutions[0].description} (score: ${solutions[0].score})`);
+
+// For interactive deployment, use MCP tools:
+// recommend → chooseSolution → answerQuestion → generateManifests
+```
+
+## TypeScript Interfaces
+
+### Discovery Engine
+
+```typescript
+class KubernetesDiscovery {
+  // Connection management
+  async connect(): Promise<void>
+  isConnected(): boolean
+  
+  // Resource discovery
+  async getAPIResources(): Promise<EnhancedResource[]>
+  async discoverCRDs(): Promise<EnhancedCRD[]>
+  async discoverResources(): Promise<ResourceMap>
+  
+  // Schema introspection
+  async explainResource(resource: string): Promise<ResourceExplanation>
+  
+  // Cluster analysis
+  async getClusterInfo(): Promise<ClusterInfo>
+  async fingerprintCluster(): Promise<ClusterFingerprint>
+  
+  // Configuration
+  getKubeconfigPath(): string
+  setKubeconfigPath(path: string): void
+}
+```
+
+### Resource Recommendation
+
+```typescript
+class ResourceRecommender {
+  constructor(config: AIRankingConfig)
+  
+  async findBestSolutions(
+    intent: string,
+    discoverResourcesFn: () => Promise<any>,
+    explainResourceFn: (resource: string) => Promise<any>
+  ): Promise<ResourceSolution[]>
+}
+
+interface ResourceSolution {
+  id: string;
+  type: 'single' | 'combination';
+  resources: ResourceSchema[];
+  score: number;
+  description: string;
+  reasons: string[];
+  analysis: string;
+  questions: QuestionGroup;
+}
+```
+
+### Stage-Based Workflow (Current)
+
+```typescript
+// New stage-based workflow via MCP tools:
+// 1. recommend: Get solutions
+// 2. chooseSolution: Select preferred solution  
+// 3. answerQuestion: Progressive configuration (required → basic → advanced → open)
+// 4. generateManifests: AI-generated Kubernetes YAML
+
+// Legacy SolutionEnhancer (see /src/legacy/ directory for reference)
+```
+
+interface QuestionGroup {
+  required: Question[];
+  basic: Question[];
+  advanced: Question[];
+  open: {
+    question: string;
+    placeholder: string;
+    answer?: string;
+  };
+}
+```
+
+### Data Structures
+
+```typescript
+interface EnhancedResource {
+  kind: string;
+  group: string;
+  version: string;
+  apiVersion: string;
+  namespaced: boolean;
+  verbs: string[];
+  shortNames?: string[];
+  categories?: string[];
+}
+
+interface EnhancedCRD {
+  name: string;
+  group: string;
+  version: string;
+  kind: string;
+  scope: 'Namespaced' | 'Cluster';
+  versions: Array<{
+    name: string;
+    served: boolean;
+    storage: boolean;
+    schema?: any;
+  }>;
+}
+
+interface ResourceExplanation {
+  kind: string;
+  version: string;
+  group: string;
+  description: string;
+  fields: Array<{
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+  }>;
+}
+
+interface ClusterFingerprint {
+  version: string;
+  platform: string;
+  nodes: {
+    count: number;
+    architecture: string[];
+    operatingSystem: string[];
+  };
+  networking: {
+    cni: string;
+    serviceCIDR: string;
+    podCIDR: string;
+  };
+  storage: {
+    classes: string[];
+    defaultClass: string;
+  };
+  features: string[];
+  operators: string[];
+}
+```
+
+## CLI Integration
+
+### Building CLI Applications
+
+```typescript
+import { CliInterface } from './src/interfaces/cli';
+import { DotAI } from './src/core';
+
+const dotAI = new DotAI();
+const cli = new CliInterface(dotAI);
+
+// Execute commands programmatically
+const result = await cli.executeCommand('discover', { 
+  output: 'json' 
+});
+
+if (result.success) {
+  console.log('Discovery results:', result.data);
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+### Custom Command Handling
+
+```typescript
+// Add custom command handling
+cli.addCustomCommand('my-command', async (options) => {
+  const discovery = new KubernetesDiscovery();
+  await discovery.connect();
+  
+  // Custom logic here
+  return {
+    success: true,
+    data: { message: 'Custom command executed' }
+  };
+});
+```
+
+## MCP Server Integration
+
+### Starting MCP Server
+
+```typescript
+import { McpInterface } from './src/interfaces/mcp';
+
+const mcpServer = new McpInterface();
+await mcpServer.start();
+
+// Server provides discovery capabilities as structured tools
+// Compatible with Cursor, Claude Code, and other MCP clients
+```
+
+### MCP Tools Available
+
+**Stage-Based Deployment Workflow:**
+- `recommend`: AI-powered resource recommendations based on intent
+- `chooseSolution`: Select a solution and get configuration questions
+- `answerQuestion`: Answer configuration questions progressively by stage
+- `generateManifests`: Generate final Kubernetes YAML manifests
+
+**Cluster Discovery:**
+- `discover_resources`: Discover all cluster resources
+- `explain_resource`: Get detailed resource schema
+- `fingerprint_cluster`: Analyze cluster capabilities
+
+## Error Handling
+
+### Common Error Patterns
+
+```typescript
+try {
+  const discovery = new KubernetesDiscovery();
+  await discovery.connect();
+} catch (error) {
+  if (error.message.includes('ENOTFOUND')) {
+    console.error('Cannot connect to cluster - check kubeconfig');
+  } else if (error.message.includes('Unauthorized')) {
+    console.error('Authentication failed - check credentials');
+  } else {
+    console.error('Discovery failed:', error.message);
+  }
+}
+```
+
+### Graceful Degradation
+
+```typescript
+// Handle partial failures gracefully
+const results = await discovery.discoverResources();
+
+if (results.resources.length === 0) {
+  console.warn('No standard resources found');
+}
+
+if (results.custom.length === 0) {
+  console.warn('No custom resources found - limited operator support');
+}
+
+// Continue with available resources
+```
+
+## Stage-Based Deployment Workflow
+
+### Interactive Deployment Process
+
+The new stage-based workflow provides a conversational approach to application deployment through progressive question answering.
+
+#### Step 1: Get AI Recommendations
+
+```bash
+# Start MCP server
+npm run mcp:start
+
+# Use MCP tools for conversational workflow
+# recommend: Get AI-powered deployment recommendations
+```
+
+**MCP Tool**: `recommend`
+```typescript
+// Via MCP client (Claude Code, Cursor, etc.)
+recommend({
+  intent: "deploy a web application with database"
+})
+// Returns: Array of ranked solutions with scores and descriptions
+```
+
+#### Step 2: Choose Solution
+
+```typescript
+// Select your preferred solution
+chooseSolution({
+  solutionId: "sol_2025-07-01T123456_abc123def456"
+})
+// Returns: Configuration questions for the selected solution
+```
+
+#### Step 3: Progressive Configuration
+
+Answer questions in stages to build your deployment configuration:
+
+**Required Stage:**
+```typescript
+answerQuestion({
+  solutionId: "sol_2025-07-01T123456_abc123def456",
+  stage: "required",
+  answers: {
+    "name": "my-web-app",
+    "namespace": "production",
+    "image": "nginx:1.21",
+    "replicas": 3
+  }
+})
+```
+
+**Basic Stage:**
+```typescript
+answerQuestion({
+  solutionId: "sol_2025-07-01T123456_abc123def456", 
+  stage: "basic",
+  answers: {
+    "port": 8080,
+    "service-type": "ClusterIP",
+    "storage-size": "10Gi"
+  }
+})
+```
+
+**Advanced Stage:**
+```typescript
+answerQuestion({
+  solutionId: "sol_2025-07-01T123456_abc123def456",
+  stage: "advanced", 
+  answers: {
+    "scaling-enabled": true,
+    "resource-requests-cpu": "500m",
+    "resource-requests-memory": "512Mi"
+  }
+})
+```
+
+**Open Requirements:**
+```typescript
+answerQuestion({
+  solutionId: "sol_2025-07-01T123456_abc123def456",
+  stage: "open",
+  answers: {
+    "open": "I need PostgreSQL database with 1000 RPS capacity and SSL termination"
+  }
+})
+```
+
+#### Step 4: Generate Manifests
+
+```typescript
+generateManifests({
+  solutionId: "sol_2025-07-01T123456_abc123def456"
+})
+// Returns: Production-ready Kubernetes YAML manifests
+```
+
+### Benefits of Stage-Based Approach
+
+**Progressive Disclosure:**
+- Questions presented in logical order (required → basic → advanced → open)
+- Users can skip stages they don't need to configure
+- No overwhelming JSON construction required
+
+**Better Error Recovery:**
+- Clear guidance at each stage
+- Validation happens per stage
+- Easy to retry with corrections
+
+**Conversational Flow:**
+- Natural interaction pattern
+- AI can provide context and suggestions
+- Supports iterative refinement through open requirements
+
+### Session Management
+
+Each deployment session is identified by a unique `solutionId` that maintains state across the workflow:
+
+```typescript
+// Session data stored in DOT_AI_SESSION_DIR
+// Contains solution configuration, answers, and generated manifests
+// Enables resuming interrupted workflows
+```
+
+## Environment Configuration
+
+### Required Environment Variables
+
+```bash
+# Optional: Custom kubeconfig location
+export KUBECONFIG=/path/to/your/kubeconfig.yaml
+
+# Required for AI features: Claude AI API key
+export ANTHROPIC_API_KEY=your_api_key_here
+
+# Optional: Debug logging
+export DEBUG=dot-ai:*
+```
+
+### Configuration Options
+
+```typescript
+interface DiscoveryConfig {
+  kubeconfigPath?: string;
+  timeout?: number;
+  retries?: number;
+  namespace?: string;
+}
+
+interface AIRankingConfig {
+  claudeApiKey: string;
+  model?: string;
+  timeout?: number;
+}
+```

package/docs/CONTEXT.md

@@ -0,0 +1,49 @@
+# Quick Context for New Sessions
+
+## Project: DevOps AI Toolkit - Kubernetes Application Management
+
+**Core Concept**: Dual-mode AI agent (CLI + MCP) that deploys applications to ANY Kubernetes cluster through dynamic discovery.
+
+## Key Architectural Decisions Made
+
+1. **Discovery-Driven**: No hardcoded platforms - discovers CRDs + core K8s resources via `kubectl explain`
+2. **Resource-Agnostic**: Works with ANY Kubernetes resources (AppClaim, CloudRun, Knative, standard K8s, custom CRDs, etc.)
+3. **Dual-Mode**: Same intelligence, two interfaces:
+   - **Direct Mode**: `dot-ai` CLI for direct user interaction
+   - **MCP Mode**: `dot-ai-mcp` server for AI agent integration
+4. **Claude Code SDK**: Powers both modes with intelligent conversation and JSON output
+5. **Memory-Enhanced**: Learns from deployments, stores lessons in JSON files
+
+## Workflow (Both Modes)
+1. **Cluster Discovery** - `kubectl get crd`, `kubectl explain`, `kubectl api-resources`
+2. **Strategy Selection** - Choose best available resource type based on discovery
+3. **Configuration Gathering** - Dynamic questions based on resource schemas + user intent
+4. **Manifest Generation** - Generate using schemas + apply memory lessons
+5. **Deployment & Monitoring** - Deploy and track until success/failure
+
+## MCP Functions to Specify
+- `create_application` - Entry point, returns discovery + initial guidance
+- `continue_workflow` - Progress based on user input
+- `deploy_application` - Execute deployment
+- `get_deployment_status` - Monitor progress
+- Plus any additional functions needed
+
+## Critical Principles
+- **Questions are schema-driven**: `kubectl explain <resource>` → generate contextual questions
+- **User intent matters**: "web app with scaling" vs "batch job" → different question focus
+- **Universal extensibility**: Must work with ANY CRDs without code changes
+- **Memory integration**: Learn from patterns, failures, successes
+
+## Files Available
+- `design.md` - Complete architecture and examples
+- `ORIGINAL_INSPIRATION.md` - The original prompt that started this project (for reference only)
+- `NEXT_STEPS.md` - Detailed action plan for immediate next development tasks
+- This `CONTEXT.md` - Quick reference for new sessions
+
+## Next Task: API Specifications
+Define detailed JSON schemas and examples for all MCP functions, focusing on:
+1. Input/output schemas for each function
+2. Error handling patterns
+3. Workflow state management
+4. Discovery result structures
+5. Memory lesson formats 

package/docs/DEVELOPMENT.md

@@ -0,0 +1,203 @@
+# Development Guide
+
+## Architecture
+
+### Core Components
+
+- **Discovery Engine** (`src/core/discovery.ts`): Comprehensive Kubernetes cluster discovery and analysis
+- **AI Integration** (`src/core/claude.ts`): Claude AI integration for intelligent application construction  
+- **Schema Parser** (`src/core/schema.ts`): Resource schema parsing, validation, and AI-powered recommendations
+- **Stage-Based Workflow Tools** (`src/tools/`): MCP tools for progressive configuration (recommend, chooseSolution, answerQuestion, generateManifests)
+- **Memory System** (`src/core/memory.ts`): Persistent memory for learning and context retention
+- **Workflow Engine** (`src/core/workflow.ts`): Orchestrates the application construction process
+- **CLI Interface** (`src/interfaces/cli.ts`): Command-line interface for direct usage
+- **MCP Interface** (`src/interfaces/mcp.ts`): Model Context Protocol server for tool integration
+
+### Data Structures
+
+The discovery engine provides comprehensive, unfiltered data through well-defined TypeScript interfaces:
+
+- **`EnhancedResource`**: Standard Kubernetes resources with metadata
+- **`EnhancedCRD`**: Custom Resource Definitions with version and schema info
+- **`ResourceExplanation`**: Detailed field-level schema information
+- **`ClusterFingerprint`**: Comprehensive cluster capabilities and configuration
+- **`ResourceMap`**: Container for all discovered resources
+
+## Development Workflow
+
+### Prerequisites
+- Node.js 18+
+- TypeScript
+- kubectl configured with cluster access
+- Access to a Kubernetes cluster (local or remote)
+
+### Setup
+
+```bash
+# Clone and install
+git clone https://github.com/vfarcic/node dist/cli.js.git
+cd node dist/cli.js
+npm install
+
+# Build the project
+npm run build
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env with your API keys
+```
+
+### Making Changes
+
+1. **Make changes** to source files in `src/`
+2. **Build** the project: `npm run build`
+3. **Run tests** to ensure functionality: `npm test`
+4. **Test manually** with real cluster: `node dist/cli.js discover --kubeconfig kubeconfig.yaml`
+5. **Commit changes** with descriptive messages
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run specific test suite
+npm test -- tests/core.test.ts
+
+# Run tests matching pattern
+npm test -- --testNamePattern="generateManifests"
+```
+
+### Test Coverage
+
+The project maintains comprehensive test coverage:
+- **Unit Tests**: Core functionality and error conditions
+- **Integration Tests**: Real cluster connectivity using kind cluster
+- **TDD Tests**: Error handling and graceful degradation scenarios
+- **Manual Validation**: CLI output verification and data structure validation
+
+Current coverage: **69%+ overall** with **565+ tests** across 21 test suites, including comprehensive tests for the stage-based workflow functionality.
+
+### Code Quality
+
+- **TypeScript**: Maintain strict type safety
+- **ESLint**: Follow existing linting rules
+- **Testing**: Write tests for new functionality
+- **Documentation**: Update docs for API changes
+- **Error Handling**: Follow patterns in [Error Handling Guide](error-handling.md)
+
+## Contributing
+
+### Development Guidelines
+
+- **Write tests** for new functionality
+- **Maintain** TypeScript type safety
+- **Follow** existing code patterns and conventions
+- **Update documentation** for API changes
+- **Test manually** with real clusters when possible
+
+### Pull Request Process
+
+1. **Fork** the repository
+2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
+3. **Make** your changes with tests
+4. **Ensure** all tests pass: `npm test`
+5. **Commit** your changes: `git commit -m 'Add amazing feature'`
+6. **Push** to the branch: `git push origin feature/amazing-feature`
+7. **Open** a Pull Request
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+# Example GitHub Actions workflow
+- name: Test cluster discovery
+  run: |
+    # Start kind cluster
+    kind create cluster --config kind-config.yaml
+    
+    # Test discovery
+    node dist/cli.js discover --kubeconfig ~/.kube/config
+    
+    # Run full test suite
+    npm test
+```
+
+### Local Testing with Kind
+
+```bash
+# Create test cluster
+kind create cluster --name node dist/cli.js-test
+
+# Run integration tests
+export KUBECONFIG=$(kind get kubeconfig-path --name node dist/cli.js-test)
+npm test -- tests/integration
+
+# Cleanup
+kind delete cluster --name node dist/cli.js-test
+```
+
+## Debugging
+
+### Common Issues
+
+**Connection Errors**
+- Verify kubeconfig path and permissions
+- Check cluster connectivity: `kubectl cluster-info`
+- Ensure proper RBAC permissions for discovery operations
+
+**API Discovery Failures**
+- Some resources may require specific cluster configurations
+- CRD discovery depends on installed operators
+- Permission issues may limit resource visibility
+
+**AI Integration Issues**
+- Verify `ANTHROPIC_API_KEY` environment variable
+- Check API rate limits and quotas
+- Review error logs for specific AI service issues
+
+### Debug Logging
+
+```bash
+# Enable verbose logging
+DEBUG=node dist/cli.js:* node dist/cli.js discover
+
+# Specific module debugging
+DEBUG=node dist/cli.js:discovery node dist/cli.js discover
+DEBUG=node dist/cli.js:schema node dist/cli.js recommend --intent "test"
+
+# MCP server debugging
+DEBUG=node dist/cli.js:* npm run mcp:start
+```
+
+## Performance Considerations
+
+- **Resource Discovery**: Can be slow in large clusters with many CRDs
+- **AI Operations**: Network latency affects recommendation speed
+- **Session Management**: generateManifests can take 30-45 seconds for complex deployments
+- **Memory Usage**: Large cluster discoveries may consume significant memory
+- **MCP Server**: Designed for persistent connection with multiple tool calls
+- **Caching**: Consider implementing caching for repeated operations
+
+## Roadmap
+
+- [x] **Stage-Based Workflow**: Completed conversational deployment via MCP tools
+- [x] **AI-Generated Manifests**: Schema-aware YAML generation with validation
+- [ ] **Enhanced AI Integration**: More sophisticated application construction strategies
+- [ ] **Multi-Cluster Support**: Discovery and deployment across multiple clusters
+- [ ] **Operator Marketplace**: Integration with operator catalogs and marketplaces
+- [ ] **Visual Interface**: Web-based cluster visualization and application designer
+- [ ] **GitOps Integration**: Automated deployment pipeline integration
+- [ ] **Policy Engine**: Security and compliance policy validation
+
+## Legacy Code
+
+Legacy components are archived in `/src/legacy/` directory:
+- **Solution Enhancer** (`src/legacy/core/solution-enhancer.ts`): Original JSON-based enhancement approach
+- **Enhance Tool** (`src/legacy/tools/enhance-solution.ts`): CLI enhancement command
+
+These are kept for reference and can be safely removed after 6 months of new architecture stability.