cli/readme.plan.md

GitZone Services Command Implementation Plan

Overview

Implement the gitzone services command to manage MongoDB and MinIO containers for development projects.

Tasks

Module Structure Setup

• Create ts/mod_services/ directory
• Create mod.plugins.ts with required imports
• Create helpers.ts with utility functions
• Create classes.serviceconfiguration.ts for config handling
• Create classes.dockercontainer.ts for Docker operations
• Create classes.servicemanager.ts for service management
• Create index.ts with main command logic

Core Functionality

• Implement ServiceConfiguration class

  • Load/create .nogit/env.json configuration
  • Generate random available ports (20000-30000 range)
  • Preserve existing custom values
  • Provide default values for missing fields

• Implement DockerContainer class

  • Check container status
  • Start/stop/restart containers
  • Execute Docker commands
  • Handle container logs
  • Manage volumes and port bindings

• Implement ServiceManager class

  • Manage MongoDB containers
  • Manage MinIO containers
  • Handle container lifecycle
  • Generate project-specific container names
  • Manage data directories in .nogit/
  • Generate MongoDB Compass connection strings

Commands Implementation

• start command - Start services (mongo|s3|all)
• stop command - Stop services (mongo|s3|all)
• restart command - Restart services (mongo|s3|all)
• status command - Show service status
• config command - Show current configuration
• compass command - Show MongoDB Compass connection string
• logs command - Show service logs with line count
• remove command - Remove containers (preserve data)
• clean command - Remove containers and data

Integration

• Add @push.rocks/smartshell to main plugins.ts
• Add @push.rocks/smartnetwork to main plugins.ts
• Add @push.rocks/smartinteraction to main plugins.ts
• Register services command in gitzone.cli.ts

Features

• Auto-configuration with smart defaults
• Random port assignment to avoid conflicts
• Project isolation with unique container names
• Data persistence in .nogit/ directories
• Status display (running/stopped/not installed)
• Interactive confirmations for destructive operations
• Colored console output
• MinIO bucket auto-creation
• 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

{
  "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

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.