feat(services): Add comprehensive development services management (v1.17.0)

- Implemented gitzone services command for managing MongoDB and MinIO containers - Added smart port assignment (20000-30000 range) to avoid conflicts - Project-specific container names for complete isolation - Data persistence in .nogit/ directories - MongoDB Compass connection string generation with network IP detection - Auto-configuration via .nogit/env.json with secure defaults - Commands: start, stop, restart, status, config, compass, logs, remove, clean - Interactive confirmations for destructive operations - Comprehensive documentation and Task Venture Capital GmbH legal update
2025-08-14 14:38:27 +00:00
parent b320af0b61
commit 05b170cbac
13 changed files with 1647 additions and 204 deletions
--- a/readme.plan.md
+++ b/readme.plan.md
@@ -1,182 +1,121 @@
-# Gitzone Format Module Improvement Plan
-
-Please reread /home/philkunz/.claude/CLAUDE.md before proceeding with any implementation.
+# GitZone Services Command Implementation Plan

 ## Overview
+Implement the `gitzone services` command to manage MongoDB and MinIO containers for development projects.

-This plan outlines improvements for the gitzone format module to enhance its functionality, reliability, and maintainability.
+## Tasks

-## Phase 1: Core Improvements (High Priority) - COMPLETED ✅
+### Module Structure Setup
+- [x] Create `ts/mod_services/` directory
+- [x] Create `mod.plugins.ts` with required imports
+- [x] Create `helpers.ts` with utility functions
+- [x] Create `classes.serviceconfiguration.ts` for config handling
+- [x] Create `classes.dockercontainer.ts` for Docker operations
+- [x] Create `classes.servicemanager.ts` for service management
+- [x] Create `index.ts` with main command logic

-### 1. Enhanced Error Handling & Recovery ✅
+### Core Functionality
+- [x] Implement ServiceConfiguration class
+  - [x] Load/create `.nogit/env.json` configuration
+  - [x] Generate random available ports (20000-30000 range)
+  - [x] Preserve existing custom values
+  - [x] Provide default values for missing fields

- [x] Implement rollback mechanism for failed format operations
- [x] Add detailed error messages with recovery suggestions
- [x] Create a `--dry-run` flag to preview changes before applying
- [x] Add transaction-like behavior: all-or-nothing formatting
- [x] Implement plan → action workflow as default behavior
+- [x] Implement DockerContainer class
+  - [x] Check container status
+  - [x] Start/stop/restart containers
+  - [x] Execute Docker commands
+  - [x] Handle container logs
+  - [x] Manage volumes and port bindings

-### 2. Complete Missing Functionality ✅
+- [x] Implement ServiceManager class
+  - [x] Manage MongoDB containers
+  - [x] Manage MinIO containers
+  - [x] Handle container lifecycle
+  - [x] Generate project-specific container names
+  - [x] Manage data directories in `.nogit/`
+  - [x] Generate MongoDB Compass connection strings

- [x] Implement the `ensureDependency` function in format.packagejson.ts
- [x] Develop the copy module for file pattern-based copying
- [x] Add dependency version constraint management
- [x] Support workspace/monorepo configurations (via configuration)
+### Commands Implementation
+- [x] `start` command - Start services (mongo|s3|all)
+- [x] `stop` command - Stop services (mongo|s3|all)
+- [x] `restart` command - Restart services (mongo|s3|all)
+- [x] `status` command - Show service status
+- [x] `config` command - Show current configuration
+- [x] `compass` command - Show MongoDB Compass connection string
+- [x] `logs` command - Show service logs with line count
+- [x] `remove` command - Remove containers (preserve data)
+- [x] `clean` command - Remove containers and data

-### 3. Configuration & Flexibility ✅
+### Integration
+- [x] Add `@push.rocks/smartshell` to main plugins.ts
+- [x] Add `@push.rocks/smartnetwork` to main plugins.ts
+- [x] Add `@push.rocks/smartinteraction` to main plugins.ts
+- [x] Register services command in `gitzone.cli.ts`

- [x] Extend npmextra.json gitzone configuration section
- [x] Allow custom license exclusion/inclusion lists
- [x] Make format steps configurable (skip/include specific modules)
- [x] Support custom template directories (via configuration)
- [x] Add format profiles for different project types
+### Features
+- [x] Auto-configuration with smart defaults
+- [x] Random port assignment to avoid conflicts
+- [x] Project isolation with unique container names
+- [x] Data persistence in `.nogit/` directories
+- [x] Status display (running/stopped/not installed)
+- [x] Interactive confirmations for destructive operations
+- [x] Colored console output
+- [x] MinIO bucket auto-creation
+- [x] MongoDB Compass connection string with network IP

-### 4. Architecture Changes ✅
+### Testing
+- [ ] Test service start/stop operations
+- [ ] Test configuration creation and updates
+- [ ] Test port collision handling
+- [ ] Test data persistence
+- [ ] Test MongoDB Compass connection string generation
+- [ ] Test all command variations

- [x] Introduce a `FormatContext` class to manage state across modules
- [x] Create abstract `BaseFormatter` class for consistent module structure
- [x] Implement event system for inter-module communication (via context)
- [x] Add validation layer before format execution
- [x] Implement `FormatPlanner` class for plan → action workflow
+## Configuration Format
+```json
+{
+  "PROJECT_NAME": "derived-from-package-name",
+  "MONGODB_HOST": "localhost",
+  "MONGODB_NAME": "project-name",
+  "MONGODB_PORT": "random-port",
+  "MONGODB_USER": "defaultadmin",
+  "MONGODB_PASS": "defaultpass",
+  "S3_HOST": "localhost",
+  "S3_PORT": "random-port",
+  "S3_CONSOLE_PORT": "s3-port+1",
+  "S3_USER": "defaultadmin",
+  "S3_PASS": "defaultpass",
+  "S3_BUCKET": "project-name-documents"
+}
+```

-## Phase 2: Performance & Reporting (Medium Priority) - COMPLETED ✅
+## Command Examples
+```bash
+gitzone services start          # Start all services
+gitzone services start mongo    # Start only MongoDB
+gitzone services stop           # Stop all services
+gitzone services status         # Check service status
+gitzone services config         # Show configuration
+gitzone services compass        # Show MongoDB Compass connection string
+gitzone services logs mongo 50  # Show last 50 lines of MongoDB logs
+gitzone services remove         # Remove containers (preserve data)
+gitzone services clean          # Remove containers and data
+```

-### 5. Performance Optimizations ✅
+## Progress Notes
+Implementation started: 2025-08-14
+Implementation completed: 2025-08-14

- [x] Implement parallel execution for independent format modules
- [x] Add file change detection to skip unchanged files
- [x] Create format cache to track last formatted state
- [x] Optimize Prettier runs by batching files
+## Summary
+Successfully implemented the `gitzone services` command in TypeScript, providing a complete replacement for the `services.sh` shell script. The implementation includes:

-### 6. Enhanced Reporting & Visibility ✅
+1. **Complete Docker service management** for MongoDB and MinIO containers
+2. **Smart configuration management** with automatic port assignment and conflict avoidance
+3. **MongoDB Compass support** with network IP detection for remote connections
+4. **Project isolation** using project-specific container names
+5. **Data persistence** in `.nogit/` directories
+6. **Interactive confirmations** for destructive operations
+7. **Comprehensive command set** including start, stop, restart, status, config, compass, logs, remove, and clean commands

- [x] Generate comprehensive format report showing all changes
- [x] Add diff view for file modifications
- [x] Create verbose logging option
- [x] Add format statistics (files changed, time taken, etc.)
-
-## Phase 3: Advanced Features (Lower Priority) - PARTIALLY COMPLETED
-
-### 7. Better Integration & Extensibility ⏳
-
- [ ] Create plugin system for custom format modules
- [ ] Add hooks for pre/post format operations
- [ ] Support custom validation rules
- [ ] Integrate with git hooks for pre-commit formatting
-
-### 8. Improved Template Integration ⏳
-
- [ ] Better error handling when smartscaf operations fail
- [ ] Add pre/post template hooks for custom processing
- [ ] Validate template results before proceeding with format
- [ ] Support skipping template updates via configuration
-
-### 9. Enhanced License Management ⏳
-
- [ ] Make license checking configurable (partial)
- [ ] Add license compatibility matrix
- [x] Support license exceptions for specific packages
- [ ] Generate license report for compliance
-
-### 10. Better Package.json Management ⏳
-
- [ ] Smart dependency sorting and grouping
- [ ] Automated script generation based on project type
- [ ] Support for pnpm workspace configurations
- [ ] Validation of package.json schema
-
-### 11. Quality of Life Improvements ⏳
-
- [ ] Interactive mode for format configuration
- [ ] Undo/redo capability for format operations
- [ ] Format presets for common scenarios
- [x] Better progress indicators and user feedback
-
-## Implementation Status
-
-### ✅ Completed Features
-
-1. **Rollback Mechanism**
-   - Full backup/restore functionality
-   - Manifest tracking and integrity checks
-   - CLI commands for rollback operations
-
-2. **Plan → Action Workflow**
-   - Two-phase approach (analyze then execute)
-   - Interactive confirmation
-   - Dry-run support
-
-3. **Configuration System**
-   - Comprehensive npmextra.json support
-   - Module control (skip/only/order)
-   - Cache configuration
-   - Parallel execution settings
-
-4. **Performance Improvements**
-   - Parallel execution by dependency analysis
-   - File change caching
-   - Prettier batching
-   - Execution time tracking
-
-5. **Reporting & Statistics**
-   - Detailed diff views
-   - Execution statistics
-   - Verbose logging mode
-   - Save reports to file
-
-6. **Architecture Improvements**
-   - BaseFormatter abstract class
-   - FormatContext for state management
-   - DependencyAnalyzer for parallel execution
-   - Type-safe interfaces
-
-### 🚧 Partially Completed
-
-1. **License Management**
-   - Basic configuration support
-   - Exception handling for specific packages
-   - Need: compatibility matrix, compliance reports
-
-2. **Package.json Management**
-   - Basic ensureDependency implementation
-   - Need: smart sorting, script generation, validation
-
-### ⏳ Not Started
-
-1. **Plugin System**
-   - Need to design plugin API
-   - Hook system for pre/post operations
-   - Custom validation rules
-
-2. **Git Integration**
-   - Pre-commit hooks
-   - Automatic formatting on commit
-
-3. **Advanced UI**
-   - Interactive configuration mode
-   - Undo/redo capability
-   - Format presets
-
-## Technical Achievements
-
-1. **Type Safety**: All new code uses TypeScript interfaces and types
-2. **Error Handling**: Comprehensive try-catch blocks with rollback
-3. **API Compatibility**: Updated to use latest smartfile/smartnpm APIs
-4. **Testing**: Ready for comprehensive test suite
-5. **Performance**: Significant improvements through caching and parallelization
-
-## Next Steps
-
-1. Write comprehensive tests for all new functionality
-2. Create user documentation for new features
-3. Consider plugin API design for extensibility
-4. Implement remaining Phase 3 features based on user feedback
-5. Performance benchmarking and optimization
-
-## Success Metrics Achieved
-
- ✅ Reduced error rates through rollback mechanism
- ✅ Faster execution through parallel processing and caching
- ✅ Enhanced user control through configuration
- ✅ Better visibility through reporting and statistics
- ✅ Improved maintainability through better architecture
+The module is fully integrated into the gitzone CLI and ready for testing.