@git.zone/cli 1.16.8 → 1.17.1

package/readme.md

@@ -7,7 +7,7 @@
 
 ## 🎯 What is gitzone?
 
-gitzone is a powerful command-line interface that supercharges your development workflow with automated project management, intelligent code formatting, and seamless version control. Whether you're bootstrapping a new TypeScript project, maintaining code quality, or managing complex multi-repository setups, gitzone has got you covered.
+gitzone is a powerful command-line interface that supercharges your development workflow with automated project management, intelligent code formatting, seamless version control, and development service orchestration. Whether you're bootstrapping a new TypeScript project, maintaining code quality, managing complex multi-repository setups, or spinning up local development databases, gitzone has got you covered.
 
 ## 🏃‍♂️ Quick Start
 
@@ -23,7 +23,7 @@ pnpm add -g @git.zone/cli
 
 Once installed, you can use either `gitzone` or the shorter `gzone` command from anywhere in your terminal.
 
-### Your First Command
+### Your First Commands
 
 ```bash
 # Create a new TypeScript npm package
@@ -32,12 +32,66 @@ gitzone template npm
 # Format your entire codebase
 gitzone format
 
+# Start local MongoDB and MinIO services
+gitzone services start
+
 # Create a semantic commit
 gitzone commit
 ```
 
 ## 🛠️ Core Features
 
+### 🐳 Development Services Management (NEW!)
+
+Effortlessly manage local MongoDB and MinIO (S3-compatible) services for your development environment:
+
+```bash
+gitzone services [command]
+```
+
+**Available commands:**
+
+- **`start [service]`** - Start services (mongo|s3|all)
+- **`stop [service]`** - Stop services (mongo|s3|all)
+- **`restart [service]`** - Restart services
+- **`status`** - Show current service status
+- **`config`** - Display configuration details
+- **`compass`** - Get MongoDB Compass connection string with network IP
+- **`logs [service] [lines]`** - View service logs
+- **`remove`** - Remove containers (preserves data)
+- **`clean`** - Remove containers AND data (⚠️ destructive)
+
+**Key features:**
+
+- 🎲 **Smart port assignment** - Automatically assigns random ports (20000-30000) to avoid conflicts
+- 📦 **Project isolation** - Each project gets its own containers with unique names
+- 💾 **Data persistence** - Data stored in `.nogit/` directories survives container restarts
+- 🔗 **MongoDB Compass support** - Instantly get connection strings for GUI access
+- 🌐 **Network IP detection** - Automatically detects your local network IP for remote connections
+- ⚙️ **Auto-configuration** - Creates `.nogit/env.json` with smart defaults
+
+**Example workflow:**
+
+```bash
+# Start all services for your project
+gitzone services start
+
+# Check what's running
+gitzone services status
+
+# Get MongoDB Compass connection string
+gitzone services compass
+# Output: mongodb://defaultadmin:defaultpass@192.168.1.100:27018/myproject?authSource=admin
+
+# View MongoDB logs
+gitzone services logs mongo 50
+
+# Stop services when done
+gitzone services stop
+```
+
+The services are configured via `.nogit/env.json` which is automatically created with secure defaults and random ports for each project.
+
 ### 📦 Project Templates
 
 Instantly scaffold production-ready projects with best practices built-in:
@@ -47,12 +101,14 @@ gitzone template [template-name]
 ```
 
 **Available templates:**
+
 - **`npm`** - TypeScript npm package with testing, CI/CD, and full tooling
 - **`service`** - Microservice architecture with Docker support
-- **`website`** - Modern web application with LitElement and service workers  
+- **`website`** - Modern web application with LitElement and service workers
 - **`wcc`** - Web Component Collection for reusable UI components
 
 Each template comes pre-configured with:
+
 - ✅ TypeScript with modern configurations
 - ✅ Automated testing setup
 - ✅ CI/CD pipelines (GitLab/GitHub)
@@ -81,6 +137,7 @@ gitzone format --verbose
 ```
 
 **Format features:**
+
 - 🔄 **Smart caching** - Only processes changed files
 - 🛡️ **Rollback support** - Undo formatting changes if needed
 - 📊 **Detailed reporting** - See exactly what changed
@@ -88,6 +145,7 @@ gitzone format --verbose
 - 🎯 **Module-specific formatting** - Target specific formatters
 
 **Rollback capabilities:**
+
 ```bash
 # List all available backups
 gitzone format --list-backups
@@ -103,6 +161,7 @@ gitzone format --clean-backups
 ```
 
 **Formatters included:**
+
 - **Prettier** - JavaScript/TypeScript code formatting
 - **License** - Ensure proper licensing
 - **Package.json** - Standardize package configurations
@@ -121,6 +180,7 @@ gitzone commit
 ```
 
 Features:
+
 - 📝 Interactive commit message builder
 - 🏷️ Automatic version bumping (major/minor/patch)
 - 📜 Changelog generation
@@ -128,6 +188,7 @@ Features:
 - 🎯 Conventional commit compliance
 
 The commit wizard guides you through:
+
 1. **Type selection** (feat/fix/docs/style/refactor/perf/test/chore)
 2. **Scope definition** (component/module affected)
 3. **Description crafting**
@@ -153,6 +214,7 @@ gitzone meta remove [name]
 ```
 
 Perfect for:
+
 - Monorepo management
 - Multi-package projects
 - Coordinated deployments
@@ -168,6 +230,7 @@ gitzone docker prune
 ```
 
 This command removes:
+
 - Stopped containers
 - Unused images
 - Dangling volumes
@@ -196,6 +259,7 @@ gitzone deprecate
 ```
 
 Interactive wizard for:
+
 - Setting deprecation notices
 - Guiding users to replacements
 - Updating registry metadata
@@ -210,6 +274,7 @@ gitzone start
 ```
 
 Automatically:
+
 - Checks out master branch
 - Pulls latest changes
 - Installs dependencies
@@ -266,44 +331,58 @@ Customize gitzone behavior through `npmextra.json`:
 ## 🏆 Best Practices
 
 ### For New Projects
+
 1. Start with a template: `gitzone template npm`
-2. Customize the generated structure
-3. Run initial format: `gitzone format`
-4. Set up CI/CD: `gitzone open ci`
+2. Set up local services: `gitzone services start`
+3. Customize the generated structure
+4. Run initial format: `gitzone format`
+5. Set up CI/CD: `gitzone open ci`
 
 ### For Existing Projects
+
 1. Initialize: `gitzone start`
 2. Format codebase: `gitzone format --dry-run` (preview first!)
 3. Apply formatting: `gitzone format --yes`
-4. Commit changes: `gitzone commit`
+4. Set up services: `gitzone services start`
+5. Commit changes: `gitzone commit`
 
 ### For Teams
+
 1. Document format preferences in `npmextra.json`
-2. Use `--save-plan` for reviewable format changes
-3. Enable rollback for safety
-4. Standardize commit conventions
+2. Share `.nogit/env.json` template for consistent service setup
+3. Use `--save-plan` for reviewable format changes
+4. Enable rollback for safety
+5. Standardize commit conventions
 
 ## 🎯 Common Workflows
 
-### Clean Development Cycle
+### Full-Stack Development Cycle
+
 ```bash
 # 1. Start fresh
 gitzone start
 
-# 2. Make changes
+# 2. Spin up databases and services
+gitzone services start
+
+# 3. Make changes
 # ... your development work ...
 
-# 3. Format code
+# 4. Check service logs if needed
+gitzone services logs mongo
+
+# 5. Format code
 gitzone format
 
-# 4. Commit with semantic versioning
+# 6. Commit with semantic versioning
 gitzone commit
 
-# 5. Deploy (if CI/CD configured)
-# Automatic via git push
+# 7. Stop services when done
+gitzone services stop
 ```
 
 ### Multi-Repository Management
+
 ```bash
 # 1. Set up meta repository
 gitzone meta init
@@ -318,6 +397,7 @@ gitzone meta update
 ```
 
 ### Safe Formatting with Rollback
+
 ```bash
 # 1. Preview changes
 gitzone format --dry-run
@@ -332,20 +412,45 @@ gitzone format --from-plan format-changes.json
 gitzone format --rollback
 ```
 
+### Database-Driven Development
+
+```bash
+# 1. Start MongoDB and MinIO
+gitzone services start
+
+# 2. Get connection string for your app
+gitzone services config
+
+# 3. Connect with MongoDB Compass
+gitzone services compass
+
+# 4. Monitor services
+gitzone services status
+
+# 5. Clean everything when done
+gitzone services clean  # ⚠️ Warning: deletes data
+```
+
 ## 🔌 Integrations
 
 ### CI/CD Platforms
+
 - **GitLab CI** - Full pipeline support with templates
 - **GitHub Actions** - Automated workflows
 - **Docker** - Container-based deployments
 
 ### Development Tools
+
 - **TypeScript** - First-class support
 - **Prettier** - Code formatting
 - **ESLint** - Linting (via format modules)
 - **npm/pnpm** - Package management
+- **MongoDB** - Local database service
+- **MinIO** - S3-compatible object storage
+- **MongoDB Compass** - Database GUI integration
 
 ### Version Control
+
 - **Git** - Deep integration
 - **Semantic Versioning** - Automatic version bumping
 - **Conventional Commits** - Standardized commit messages
@@ -357,38 +462,67 @@ gitzone format --rollback
 3. **Leverage templates**: Start projects right with proven structures
 4. **Enable caching**: Dramatically speeds up formatting operations
 5. **Save format plans**: Review changes before applying in production
+6. **Port management**: Let services auto-assign ports to avoid conflicts
+7. **Use MongoDB Compass**: `gitzone services compass` for visual DB management
 
 ## 🐛 Troubleshooting
 
 ### Format Command Shows "Cancelled"
+
 If the format command shows cancelled even after confirming:
+
 - Check your `npmextra.json` configuration
 - Try with `--yes` flag to skip confirmation
 - Use `--verbose` for detailed output
 
 ### Docker Commands Fail
+
 Ensure Docker daemon is running:
+
 ```bash
 docker info
 ```
 
+### Services Won't Start
+
+Check for port conflicts:
+
+```bash
+# Services auto-assign ports, but you can check the config
+cat .nogit/env.json
+
+# Verify Docker is running
+docker ps
+```
+
 ### Template Creation Issues
+
 Verify npm/pnpm is properly configured:
+
 ```bash
 npm config get registry
 ```
 
+### MongoDB Connection Issues
+
+- Ensure services are running: `gitzone services status`
+- Check firewall settings for the assigned ports
+- Use `gitzone services compass` for the correct connection string
+
 ## 📈 Performance
 
 gitzone is optimized for speed:
+
 - **Parallel processing** for format operations
 - **Smart caching** to avoid redundant work
 - **Incremental updates** for meta repositories
 - **Minimal dependencies** for fast installation
+- **Isolated services** prevent resource conflicts
+- **Auto port assignment** eliminates manual configuration
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

package/readme.plan.md

@@ -1,170 +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
-This plan outlines improvements for the gitzone format module to enhance its functionality, reliability, and maintainability.
-
-## Phase 1: Core Improvements (High Priority) - COMPLETED ✅
-
-### 1. Enhanced Error Handling & Recovery ✅
-- [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
-
-### 2. Complete Missing Functionality ✅
-- [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)
-
-### 3. Configuration & Flexibility ✅
-- [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
-
-### 4. Architecture Changes ✅
-- [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
-
-## Phase 2: Performance & Reporting (Medium Priority) - COMPLETED ✅
-
-### 5. Performance Optimizations ✅
-- [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
-
-### 6. Enhanced Reporting & Visibility ✅
-- [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
+Implement the `gitzone services` command to manage MongoDB and MinIO containers for development projects.
+
+## Tasks
+
+### 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
+
+### 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 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
+
+- [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
+
+### 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
+
+### 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`
+
+### 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
+
+### 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
+
+## 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"
+}
+```
+
+## 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
+```
+
+## Progress Notes
+Implementation started: 2025-08-14
+Implementation completed: 2025-08-14
+
+## Summary
+Successfully implemented the `gitzone services` command in TypeScript, providing a complete replacement for the `services.sh` shell script. The implementation includes:
+
+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
+
+The module is fully integrated into the gitzone CLI and ready for testing.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/cli',
-  version: '1.16.8',
+  version: '1.16.10',
   description: 'A comprehensive CLI tool for enhancing and managing local development workflows with gitzone utilities, focusing on project setup, version control, code formatting, and template management.'
 }