mlgym-deploy 3.3.42 → 3.3.44

package/CHANGELOG-v3.3.42.md

@@ -0,0 +1,707 @@
+# MCP v3.3.42 - Complete Application Lifecycle Management
+
+## Release Date
+2026-01-20
+
+## Overview
+
+Evolution from basic deployment (v3.0.0) to comprehensive application lifecycle management. Expanded from 2 core tools to 14 tools covering deployment, configuration, monitoring, rollback, and development environments.
+
+---
+
+## What's New Since v3.0.0
+
+### 📦 Tools Expansion: 2 → 14 Tools
+
+#### Core Deployment Tools (v3.0.0 - Retained)
+1. **`mlgym_deploy`** - Complete deployment workflow
+2. **`mlgym_status`** - Authentication and project status
+
+#### Configuration & Management Tools (NEW in v3.3.x)
+3. **`mlgym_set_env_vars`** - Environment variable management (DATABASE_URL, API keys, etc.)
+4. **`mlgym_set_health_check`** - Health check configuration (endpoint, interval, timeout)
+5. **`mlgym_set_domain`** - Custom domain/FQDN assignment
+6. **`mlgym_set_deployment_commands`** - Pre/post-deployment command hooks
+7. **`mlgym_set_options`** - Application options (build cache control)
+
+#### Deployment Operations Tools (NEW in v3.3.x)
+8. **`mlgym_deploy_logs`** - View deployment history and build logs (1-10 deployments)
+9. **`mlgym_deploy_manual`** - Manually trigger rebuild and deployment
+10. **`mlgym_rollback`** - Rollback to previous or specific deployment
+
+#### Development Tools (NEW in v3.3.x)
+11. **`deploy_dollie`** - Next.js development container with SSH access
+   - Pre-built Dollie base image
+   - Git repository cloning (public/private)
+   - SSH credentials for interactive development
+   - Automatic dev server startup
+
+#### User Management Tools (v3.0.0 - Re-enabled Legacy)
+12. **`mlgym_user_create`** - User account creation with SSH key setup
+13. **`mlgym_auth_login`** - Login with existing credentials
+
+#### Documentation
+14. **`mlgym_help`** - Interactive help system with usage examples
+
+---
+
+## New Features
+
+### 🌍 Language Support Expansion
+
+**v3.0.0 Supported:**
+- Node.js (Next.js, Express, React, Vue)
+- Python (Flask, FastAPI)
+- Static/HTML
+- Go
+
+**v3.3.42 Now Supports:**
+- ✅ Node.js (Next.js, Express, React, Vue, Nuxt, Svelte)
+- ✅ Python (Flask, FastAPI, Django)
+- ✅ Static/HTML
+- ✅ Go
+- ✅ **Scala** (sbt-assembly support) - v3.3.22-23
+- ✅ **Rust** - v3.3.35
+- ✅ **Ruby** - v3.3.19
+- ✅ **PHP** - v3.3.28
+- ✅ **Perl** - v3.3.20
+- ✅ **Elixir** - v3.3.21
+
+**Total: 10+ languages with automatic project type detection**
+
+---
+
+### 🔧 Configuration Management
+
+#### Environment Variables (v3.3.x)
+```javascript
+mlgym_set_env_vars({
+  project_name: "my-app",
+  env_vars: {
+    DATABASE_URL: "postgresql://...",
+    API_KEY: "secret123",
+    NODE_ENV: "production"
+  }
+})
+```
+
+#### Health Checks (v3.3.x)
+```javascript
+mlgym_set_health_check({
+  project_name: "my-app",
+  enabled: true,
+  path: "/health",
+  port: 3000,
+  method: "GET",
+  expected_status_codes: [200],
+  interval: 30,
+  timeout: 5,
+  retries: 3
+})
+```
+
+#### Custom Domains (v3.3.x)
+```javascript
+mlgym_set_domain({
+  project_name: "my-app",
+  domain: "myapp.example.com"  // or just "myapp" for *.ezb.net
+})
+```
+
+#### Deployment Commands (v3.3.x)
+```javascript
+mlgym_set_deployment_commands({
+  project_name: "my-app",
+  pre_deployment: "npm run migrate",
+  post_deployment: "npm run seed",
+  container: "my-app"  // for docker-compose
+})
+```
+
+#### Build Options (v3.3.x)
+```javascript
+mlgym_set_options({
+  project_name: "my-app",
+  disable_build_cache: true  // Force clean builds
+})
+```
+
+---
+
+### 📊 Deployment Monitoring & Management
+
+#### Deployment Logs (v3.3.x)
+```javascript
+mlgym_deploy_logs({
+  project_name: "my-app",  // Optional: auto-detected from git remote
+  depth: 5  // View last 5 deployments (1-10)
+})
+```
+
+**Returns:**
+- Deployment IDs and UUIDs
+- Status (running, finished, failed)
+- Timestamps (started_at, finished_at)
+- Build logs per deployment
+
+#### Manual Deployment (v3.3.x)
+```javascript
+mlgym_deploy_manual({
+  project_name: "my-app"
+})
+```
+
+Forces rebuild and deployment of current code from GitLab repository.
+
+#### Rollback (v3.3.x)
+```javascript
+// Rollback to previous deployment
+mlgym_rollback({
+  project_name: "my-app"
+})
+
+// Rollback to specific deployment
+mlgym_rollback({
+  project_name: "my-app",
+  deployment_id: 12345
+})
+```
+
+---
+
+### 🔐 Authentication Enhancements
+
+#### SSH Key Management
+
+**v3.0.0:**
+- Basic SSH key generation
+- GitLab registration
+
+**v3.3.42 Improvements:**
+- **Per-user SSH keys** (v3.3.29)
+  - Stored as `~/.ssh/mlgym_[email]`
+  - Automatic SSH config updates
+  - Per-user key switching when using MLGYM_TOKEN
+- **GitLab user ID-based key creation** (v3.3.13)
+- **SSH config auto-fix** (v3.3.25)
+  - Prevents git dubious ownership errors
+  - Replaces old keys instead of skipping
+
+#### Token Support
+
+**v3.3.19+:**
+- `MLGYM_TOKEN` environment variable authentication
+- Email extraction from JWT tokens
+- No need for `MLGYM_EMAIL` when using JWT tokens
+- Cached token management in `~/.mlgym/mcp_config.json`
+
+---
+
+### 🐳 Docker Intelligence
+
+#### Auto-Generation & Fixing
+
+**Dockerfile Auto-Generation (v3.0.0+):**
+- Automatic Dockerfile creation for missing projects
+- Language-specific templates
+- Port detection and configuration
+
+**Auto-Fixing (v3.3.x):**
+- **Base image version validation** (v3.3.35)
+  - Detects invalid Python/Node/Go versions
+  - Suggests and fixes to valid versions
+- **Docker image variant preservation** (v3.3.38)
+  - Maintains `-slim`, `-alpine`, `-bullseye` variants when fixing
+- **Port detection improvements** (v3.3.18)
+  - Preserves EXPOSE directive format
+  - Validates port configurations
+- **Language-specific fixes:**
+  - Scala: sbt-assembly plugin + fat JAR config (v3.3.22)
+  - Elixir: Dockerfile optimization (v3.3.21)
+  - Perl: Dockerfile optimization (v3.3.20)
+  - PHP: Project detection and templates (v3.3.28)
+
+#### Deployment Strategy Detection (v3.3.35)
+
+Automatically detects and suggests fixes for:
+- ❌ **Port mismatches** between Dockerfile and docker-compose.yml
+- ❌ **Missing dependencies** in package.json vs imports
+- ❌ **Invalid path aliases** in tsconfig.json
+- ❌ **Docker vs Docker Compose** strategy conflicts
+
+---
+
+### 🛠️ Development Features
+
+#### Dollie Development Containers (v3.3.42)
+
+Deploy Next.js development environments with SSH access:
+
+```javascript
+deploy_dollie({
+  project_name: "my-dev-env",
+  git_repo: "https://github.com/user/repo.git",
+  git_branch: "main",  // Optional
+  git_token: "ghp_...",  // For private repos
+  app_port: 3000  // Optional, default 3000
+})
+```
+
+**Features:**
+- Pre-built Dollie base image (Next.js + SSH)
+- Automatic git clone and npm install
+- Dev server auto-start
+- SSH access: `ssh developer@[hostname] -p [port]`
+- Dynamic password generation
+- Supports public and private repositories
+
+**Use Cases:**
+- AI-assisted development in isolated environments
+- Remote pair programming
+- Quick prototyping without local setup
+
+---
+
+### 🚀 Reliability Improvements
+
+#### Retry Logic (v3.3.12)
+- Automatic retry for 5xx server errors
+- Exponential backoff (up to 10 seconds)
+- Maximum 3 retry attempts
+- Network error handling
+
+#### Error Recovery (v3.0.0+)
+- Detailed recovery suggestions for common errors
+- Workflow step logging for debugging
+- Comprehensive error messages with context
+
+#### Auto-Fixes (v3.3.x)
+- **Project name derivation** from local_path (v3.3.11)
+- **SSH key auto-ensure** on authentication (v3.3.12)
+- **Duplicate project prevention** (v3.3.34)
+- **Slow-starting service warnings** (v3.3.30)
+  - Detects PostgreSQL, MySQL, MongoDB
+  - Suggests wait mechanisms
+
+---
+
+## Architecture Evolution
+
+### v3.0.0 - Monolithic Deployment
+```
+Tools: 2
+Focus: Deployment workflow only
+Pattern: Single-call deployment
+AI Decision Points: 3
+```
+
+### v3.3.42 - Complete Lifecycle Management
+```
+Tools: 14
+Focus: Full application lifecycle
+Pattern: Layered architecture
+  - Authentication layer
+  - Deployment layer
+  - Configuration layer
+  - Management layer
+  - Development layer
+AI Decision Points: Still ~3 per operation
+```
+
+**Key Principles Maintained:**
+- ✅ Server-side workflow orchestration
+- ✅ Minimal AI decision points
+- ✅ Deterministic execution
+- ✅ Atomic operations
+- ✅ Comprehensive state tracking
+
+**New Capabilities:**
+- ✅ Post-deployment configuration management
+- ✅ Deployment history and monitoring
+- ✅ Rollback and recovery
+- ✅ Development environment provisioning
+
+---
+
+## Comparison Table
+
+| Aspect | v3.0.0 | v3.3.42 |
+|--------|--------|---------|
+| **Tools** | 2 | 14 |
+| **Languages Supported** | 4-7 | 10+ |
+| **Environment Variables** | ❌ | ✅ |
+| **Health Checks** | ❌ | ✅ |
+| **Custom Domains** | ❌ | ✅ |
+| **Deployment Commands** | ❌ | ✅ |
+| **Deployment Logs** | ❌ | ✅ (1-10 depth) |
+| **Manual Deploy** | ❌ | ✅ |
+| **Rollback** | ❌ | ✅ (previous/specific) |
+| **Dev Containers** | ❌ | ✅ (Dollie SSH) |
+| **SSH Key Management** | Basic | Per-user with auto-fix |
+| **Token Support** | JWT only | JWT + env var |
+| **Docker Auto-Fix** | Basic | Advanced (versions, variants) |
+| **Retry Logic** | ❌ | ✅ (5xx errors) |
+| **Error Recovery** | Basic | Advanced with suggestions |
+| **Success Rate** | ~90% | ~95%+ (estimated) |
+
+---
+
+## Notable Fixes (v3.0.0 → v3.3.42)
+
+### Major Fixes
+
+**v3.3.42** - Add deploy_dollie tool for Next.js dev containers with SSH
+**v3.3.39** - Language detection and Dockerfile template fixes
+**v3.3.38** - Preserve Docker image variant when fixing base image
+**v3.3.37** - Replace glob dependency with native fs scanner
+**v3.3.35** - Auto-detection and fixes for common deployment issues
+**v3.3.34** - Fix duplicate project creation and SSH key switching
+**v3.3.32** - Fix misleading hostname description
+**v3.3.31** - Fix URL format bug in deployment status
+**v3.3.30** - Add warnings for slow-starting database services
+
+### SSH & Authentication Fixes
+
+**v3.3.29** - Fix SSH key per-user when using MLGYM_TOKEN env var
+**v3.3.25** - Fix git dubious ownership error; fix SSH config replacement
+**v3.3.24** - Fix SSH config to replace old key instead of skipping
+**v3.3.19** - Support MLGYM_TOKEN environment variable
+**v3.3.13** - Fix SSH key creation using GitLab user ID
+**v3.3.12** - Auto-ensure SSH keys on authentication
+
+### Language-Specific Fixes
+
+**v3.3.28** - Add PHP project detection and Dockerfile generation
+**v3.3.23** - Auto-organize Scala project structure
+**v3.3.22** - Auto-fix Scala sbt-assembly plugin + fat JAR config
+**v3.3.21** - Auto-fix Elixir Dockerfile
+**v3.3.20** - Auto-fix Perl Dockerfile
+**v3.3.19** - Ruby deployment support
+
+### Docker & Port Fixes
+
+**v3.3.18** - Fix Dockerfile port detection to preserve EXPOSE directive
+**v3.3.17** - Add ports_exposes for Dockerfile deployments
+**v3.3.16** - Fix ports vs expose bug + auth status check
+
+### Workflow Fixes
+
+**v3.3.27** - Fix version constant and add deployment_url debug logging
+**v3.3.26** - Fix deployment_url to use backend-provided URL
+**v3.3.12** - Add retry logic for 5xx errors
+**v3.3.11** - Auto-derive project_name from local_path
+
+---
+
+## Migration Guide
+
+### From v3.0.0 to v3.3.42
+
+**No Breaking Changes!**
+
+All v3.0.0 workflows continue to work. New tools are additive.
+
+### Using New Features
+
+#### After Initial Deployment (v3.0.0 workflow):
+```javascript
+// 1. Deploy (same as v3.0.0)
+mlgym_deploy({
+  project_name: "my-app",
+  project_description: "My awesome app"
+})
+
+// 2. Configure environment variables (NEW)
+mlgym_set_env_vars({
+  project_name: "my-app",
+  env_vars: { DATABASE_URL: "..." }
+})
+
+// 3. Set up health checks (NEW)
+mlgym_set_health_check({
+  project_name: "my-app",
+  enabled: true,
+  path: "/health"
+})
+
+// 4. Configure custom domain (NEW)
+mlgym_set_domain({
+  project_name: "my-app",
+  domain: "myapp.example.com"
+})
+```
+
+#### View Deployment History (NEW):
+```javascript
+mlgym_deploy_logs({
+  project_name: "my-app",
+  depth: 5
+})
+```
+
+#### Rollback if Needed (NEW):
+```javascript
+mlgym_rollback({
+  project_name: "my-app"
+})
+```
+
+#### Deploy Development Container (NEW):
+```javascript
+deploy_dollie({
+  project_name: "dev-env",
+  git_repo: "https://github.com/user/repo.git"
+})
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+**Authentication:**
+- `MLGYM_TOKEN` - JWT authentication token (NEW in v3.3.19)
+- `MLGYM_EMAIL` - User email (optional with MLGYM_TOKEN)
+
+**API Endpoints:**
+- `MLGYM_API_ENDPOINT` - Backend URL (default: https://backend.eu.ezb.net)
+
+**Debugging:**
+- `MLGYM_DEBUG` - Enable debug logging (default: enabled)
+- `DEBUG` - Alternative debug flag
+
+### Configuration File
+
+Location: `~/.mlgym/mcp_config.json`
+
+**Stored Data:**
+- Cached authentication token
+- User email
+- Last version check timestamp
+
+---
+
+## Technical Notes
+
+### Dependencies
+No changes from v3.0.0:
+- `@modelcontextprotocol/sdk`: ^0.6.0
+- `axios`: ^1.6.0
+
+### Version Check
+- Automatic version check every hour
+- Warns if newer version available on npm
+- Non-blocking, informational only
+
+### Debug Logging
+Enhanced colored output system:
+- 🔵 INFO - General information
+- ✅ SUCCESS - Successful operations
+- ⚠️ WARNING - Non-critical issues
+- ❌ ERROR - Critical errors
+- ⋯ DEBUG - Detailed debug information
+
+### API Integration
+
+**Backend API:**
+- URL: https://backend.eu.ezb.net
+- Endpoints: /auth/*, /projects/*, /deployments/*, /applications/*
+
+**GitLab API:**
+- URL: https://git.mlgym.io
+- Operations: Project creation, SSH key registration
+
+**Coolify User Agent:**
+- URL: http://coolify.eu.ezb.net:9000
+- Operations: Application configuration, deployment management
+
+---
+
+## Testing Recommendations
+
+### Basic Workflow Test
+```bash
+# 1. Deploy new project
+mlgym_deploy({
+  project_name: "test-app",
+  project_description: "Test application"
+})
+
+# 2. Check status
+mlgym_status()
+
+# 3. View logs
+mlgym_deploy_logs({ project_name: "test-app", depth: 1 })
+```
+
+### Configuration Test
+```bash
+# 4. Set environment variables
+mlgym_set_env_vars({
+  project_name: "test-app",
+  env_vars: { TEST_VAR: "value" }
+})
+
+# 5. Configure health check
+mlgym_set_health_check({
+  project_name: "test-app",
+  enabled: true,
+  path: "/health"
+})
+
+# 6. Trigger manual deployment
+mlgym_deploy_manual({ project_name: "test-app" })
+```
+
+### Rollback Test
+```bash
+# 7. View deployment history
+mlgym_deploy_logs({ project_name: "test-app", depth: 5 })
+
+# 8. Rollback to previous
+mlgym_rollback({ project_name: "test-app" })
+```
+
+### Development Container Test
+```bash
+# 9. Deploy Dollie dev container
+deploy_dollie({
+  project_name: "dev-test",
+  git_repo: "https://github.com/vercel/next.js/tree/canary/examples/hello-world"
+})
+```
+
+---
+
+## Success Metrics
+
+### Deployment Reliability
+- **v3.0.0**: ~90% success rate
+- **v3.3.42**: ~95%+ success rate (estimated)
+
+**Improvements from:**
+- Retry logic for transient failures
+- Auto-fix for common configuration issues
+- Better error recovery suggestions
+- Per-user SSH key management
+
+### User Experience
+- **Deployment Time**: Unchanged (~2-5 minutes)
+- **Configuration Time**: New capability (1-2 minutes per setting)
+- **Rollback Time**: New capability (~30 seconds)
+- **Dev Container Setup**: New capability (~3-5 minutes)
+
+### Tool Usage Patterns
+```
+Primary Workflow (v3.0.0 pattern):
+  mlgym_deploy → Success
+
+Extended Workflow (v3.3.42 pattern):
+  mlgym_deploy
+    → mlgym_set_env_vars
+    → mlgym_set_health_check
+    → mlgym_set_domain
+    → mlgym_deploy_logs (monitoring)
+    → mlgym_rollback (if needed)
+
+Development Workflow (v3.3.42 new):
+  deploy_dollie → SSH access → Iterate
+```
+
+---
+
+## Known Limitations
+
+### Same as v3.0.0
+- Requires backend API availability
+- GitLab must be accessible
+- Coolify User Agent must be running
+- SSH key generation requires write access to ~/.ssh/
+
+### New Considerations (v3.3.42)
+- Rollback limited to last 10 deployments (Coolify limitation)
+- Health check configuration requires application restart
+- Custom domains require DNS configuration outside MLGym
+- Dollie containers support Next.js only (currently)
+
+---
+
+## Future Considerations
+
+### Potential Enhancements
+- [ ] Multi-region deployment management
+- [ ] Environment promotion (staging → production)
+- [ ] Deployment scheduling
+- [ ] Cost tracking and optimization
+- [ ] Team collaboration features
+- [ ] Deployment approval workflows
+- [ ] Backup and restore operations
+- [ ] Dollie support for other frameworks (React, Vue, etc.)
+
+### Monitoring Integration
+- [ ] Metrics collection (CPU, memory, requests)
+- [ ] Alerting on deployment failures
+- [ ] Performance tracking over time
+- [ ] Cost analysis per deployment
+
+---
+
+## Credits
+
+**Architecture Design:** Monolithic workflow approach (v3.0.0)
+**Feature Expansion:** Application lifecycle management (v3.3.x)
+**Language Support:** Community-driven templates and auto-fixes
+**Development Tools:** Dollie SSH container integration (v3.3.42)
+
+---
+
+## Files Modified Since v3.0.0
+
+1. **mcp-server/index.js**
+   - Added 12 new tool definitions
+   - Enhanced DeploymentWorkflow class
+   - Added configuration management functions
+   - Added deployment monitoring functions
+   - Added Dollie deployment function
+   - Improved error handling and retry logic
+   - Enhanced debug logging system
+   - Added language detection for 10+ languages
+   - Added Dockerfile auto-fix capabilities
+
+2. **mcp-server/package.json**
+   - Version: 3.0.0 → 3.3.42
+   - Updated description for extended capabilities
+   - Updated mcp.tools metadata with 14 tools
+
+---
+
+## Summary
+
+v3.3.42 represents a **major capability expansion** while maintaining the **architectural principles** that made v3.0.0 successful:
+
+### What's the Same
+- ✅ Monolithic workflow approach (server-side orchestration)
+- ✅ Minimal AI decision points (~3 per operation)
+- ✅ Deterministic execution
+- ✅ High success rate (90%+)
+- ✅ Single-call deployment experience
+
+### What's New
+- ✅ **12 new tools** for complete lifecycle management
+- ✅ **10+ programming languages** supported
+- ✅ **Configuration management** (env vars, health checks, domains, commands)
+- ✅ **Deployment operations** (logs, manual deploy, rollback)
+- ✅ **Development containers** (Dollie SSH environments)
+- ✅ **Enhanced reliability** (retry logic, auto-fixes, per-user SSH)
+- ✅ **Better monitoring** (deployment history, build logs)
+
+### Impact
+From **basic deployment tool** → **comprehensive DevOps platform** for AI-assisted development.
+
+---
+
+**Version:** 3.3.42
+**Status:** ✅ Production Ready
+**Backward Compatibility:** ✅ Full (with v3.0.0)
+**Next Version:** 3.4.0 (planned: multi-region management)

package/Dockerfile

@@ -0,0 +1,7 @@
+FROM node:22-bookworm
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+EXPOSE 3000
+CMD ["npm", "start"]