just-commons/README.md

# Just Commons - Universal Command Library

**Version 2.0 - Modern Module Architecture**

A collection of universal Just command modules for container management, database operations, and development workflows. Built with Just's modern module system and designed for maximum reusability.

## 🚀 Features

- **🎯 Module-Based Architecture**: Clean separation using Just's native module system
- **🎨 Modern Just Features**: Built-in colors, groups, and confirm attributes
- **📦 Optional Modules**: Include only what you need
- **🐳 Universal Container Support**: Works with Docker and Podman
- **🗄️ Database Operations**: PostgreSQL and MySQL support
- **🔒 Built-in Safety**: Confirmation prompts for destructive operations
- **🏗️ Zero Dependencies**: Pure Just recipes with automatic runtime detection

## 📋 Requirements

### Just Command Runner

This library requires **Just 1.31.0 or later** for module support and modern features.

#### Installation on Ubuntu 24.04 LTS

**Method 1: Snap (Recommended for latest version)**
```bash
sudo snap install just --classic
```

**Method 2: Manual Installation from GitHub**
```bash
# Get the latest version
JUST_VERSION=$(curl -s "https://api.github.com/repos/casey/just/releases/latest" | grep -Po '"tag_name": "\K[0-9.]+')

# Download and install
wget -qO just.tar.gz "https://github.com/casey/just/releases/latest/download/just-${JUST_VERSION}-x86_64-unknown-linux-musl.tar.gz"
tar -xzf just.tar.gz
sudo mv just /usr/local/bin/
chmod +x /usr/local/bin/just

# Verify installation
just --version
```

#### Other Platforms
- **macOS**: `brew install just`
- **Windows**: `choco install just` or `scoop install just`
- **Other Linux**: See [official installation guide](https://github.com/casey/just#installation)

### Other Requirements
- Docker or Podman
- Git

## 🏗️ Module Architecture

```
just-commons/
├── README.md              # This documentation
├── justfile               # Main file with module declarations and help
├── core.just              # Shared utilities (imported)
├── postgres/
│   └── mod.just          # PostgreSQL module
├── mysql/
│   └── mod.just          # MySQL module
├── volumes/
│   └── mod.just          # Volume management module
├── container/
│   └── mod.just          # Container operations module
├── registry/
│   └── mod.just          # Registry authentication module
└── images/
    └── mod.just          # Image operations module
```

## 🔧 Usage

### Add as Git Submodule

```bash
git submodule add git@github.com:shadoll/just-commons.git just-commons
cd just-commons
git checkout main
```

### Import in Your Justfile

```just
# Import core utilities (required)
import 'just-commons/core.just'

# Declare optional modules (use only what you need)
mod? postgres 'just-commons/postgres'
mod? mysql 'just-commons/mysql'
mod? volumes 'just-commons/volumes'
mod? container 'just-commons/container'
mod? registry 'just-commons/registry'
mod? images 'just-commons/images'
```

### Example Project Justfile

```just
# My Project Justfile
import 'just-commons/core.just'

# Only include modules I need
mod? container 'just-commons/container'
mod? postgres 'just-commons/postgres'
mod? volumes 'just-commons/volumes'

# Project-specific commands
[group('project')]
setup:
    just container start
    just postgres sql "CREATE DATABASE myapp;"

[group('project')]
teardown:
    just volumes clean-all
```

## 📚 Available Modules

### 🐳 Container Module (`container`)

**Universal container operations with optional compose file support**

```bash
just container start [service] [compose-file]     # Start services
just container stop [service] [compose-file]      # Stop services
just container restart [service] [compose-file]   # Restart services
just container status [service] [compose-file]    # Show service status
just container logs [service] [compose-file]      # View service logs
just container shell <service> [compose-file]     # Open shell in container
just container exec <service> <cmd> [compose-file] # Execute command
```

### 🗄️ Database Modules

#### PostgreSQL Module (`postgres`)

```bash
just postgres sql <query> [service] [compose-file]        # Execute SQL query
just postgres check [service] [compose-file]              # Check connection
just postgres list-databases [service] [compose-file]     # List databases
just postgres list-users [service] [compose-file]         # List users
just postgres create-database <name> [service]            # Create database
just postgres drop-database <name> [service]              # Drop database (with confirmation)
just postgres shell [service] [compose-file]              # Interactive shell
just postgres restore <backup> [service] [compose-file]   # Restore from backup (with confirmation)
```

#### MySQL Module (`mysql`)

```bash
just mysql sql <query> [service] [compose-file]           # Execute SQL query
just mysql check [service] [compose-file]                 # Check connection
just mysql list-databases [service] [compose-file]        # List databases
just mysql list-users [service] [compose-file]            # List users
just mysql create-database <name> [service]               # Create database
just mysql drop-database <name> [service]                 # Drop database (with confirmation)
just mysql create-user <username> <password> [service]    # Create user
just mysql grant-privileges <database> <username> [service] # Grant privileges
just mysql shell [service] [compose-file]                 # Interactive shell
just mysql restore <backup> <database> [service]          # Restore from backup (with confirmation)
```

### 💾 Volume Module (`volumes`)

**Safe volume management with built-in confirmations**

```bash
just volumes clean-all [compose-file]                     # Remove all compose volumes (with confirmation)
just volumes remove <volume-name>                         # Remove specific volume (with confirmation)
just volumes remove-pattern <pattern>                     # Remove volumes matching pattern (with confirmation)
just volumes list [pattern]                               # List volumes (optionally filtered)
```

### 🐋 Images Module (`images`)

**Universal image operations with intelligent auto-discovery and cross-platform builds**

```bash
just images build [project] [tag]                         # Build project image (auto-discovers project and Containerfile)
just images push [project] [tag]                          # Push image to registry (auto-discovers project)
just images pull [project] [tag]                          # Pull image from registry (auto-discovers project)
just images tag <project> <new-tag>                       # Tag existing image
just images info [project] [tag]                          # Show image information (auto-discovers project)
just images clean [project]                               # Remove project images (auto-discovers project, with confirmation)
just images build-all                                     # Build all projects with Containerfiles (uses discovery logic)
```

**Auto-Discovery Features:**
- **Project Detection**: Automatically uses directory basename when project not specified
- **Containerfile Discovery**: Finds `Containerfile`/`Dockerfile` in current directory or `./docker/` folder
- **Cross-Platform Builds**: Handles macOS compatibility for Linux containers automatically
- **Smart Parameter Parsing**: `just images push latest` correctly interprets "latest" as tag, not project
- **Unified Discovery Logic**: Consistent behavior whether using auto-discovery or explicit project directories

### 🔐 Registry Module (`registry`)

**Container registry authentication management**

```bash
just registry login                                       # Login to container registry
just registry logout                                      # Logout from registry
just registry check                                       # Check authentication status
```

### 🔧 Core Utilities

**Shared functions, auto-discovery, and environment checking**

```bash
just env-check                                           # Check container runtime availability
just _detect_runtime                                     # Internal: Detect Docker/Podman
just _detect_compose                                     # Internal: Detect compose command
just _discover_project                                   # Internal: Auto-discover project name from directory
just _discover_containerfile_in [dir]                   # Internal: Discover Containerfile/Dockerfile in directory
just _discover_containerfile                            # Internal: Discover Containerfile/Dockerfile in current directory
```

**Auto-Discovery Functions:**
- **`_discover_project`**: Returns `$(basename $(pwd))` - the current directory name as project name
- **`_discover_containerfile_in`**: Searches for `Containerfile`/`Dockerfile` in specified directory, also checks `./docker/` subfolder when searching current directory
- **`_discover_containerfile`**: Convenience wrapper for current directory discovery

These functions enable consistent auto-discovery behavior across all modules.

## 🎨 Modern Just Features

### Built-in Colors
Uses Just's native color constants instead of custom ANSI codes:
- `{{RED}}`, `{{GREEN}}`, `{{BLUE}}`, `{{YELLOW}}`
- `{{BOLD}}`, `{{NORMAL}}`

### Command Groups
All commands are organized with `[group('name')]` attributes:
- `container` - Container operations
- `database` - Database operations
- `volumes` - Volume management
- `images` - Image operations
- `registry` - Registry operations
- `environment` - Environment checking

### Safety Confirmations
Destructive operations use `[confirm]` attribute:
- Volume removal operations
- Database dropping
- Image cleaning
- Backup restoration

## 🌍 Environment Configuration

### Registry Configuration

**Authentication vs Registry Namespace**

The system separates authentication credentials from registry image paths, allowing you to authenticate with your personal account while pushing to organization namespaces.

```bash
# .env file - Registry settings
GITHUB_USERNAME=your-auth-username    # For authentication (just registry login)
GITHUB_TOKEN=ghp_your-token          # For authentication
REGISTRY_NAMESPACE=org-or-username   # For image paths (ghcr.io/NAMESPACE/project:tag)
REGISTRY=ghcr.io                     # Registry URL (optional, defaults to ghcr.io)
```

**Configuration Hierarchy:**

1. **Registry Namespace** (for image paths):
   - `REGISTRY_NAMESPACE` (if set) - highest priority
   - `GITHUB_USERNAME` (fallback) - backward compatibility
   - Error if neither is set

2. **Registry URL**:
   - `REGISTRY` (if set) - custom registry
   - `ghcr.io` (default) - GitHub Container Registry

**Examples:**

```bash
# Organization setup
GITHUB_USERNAME=john-doe              # Personal auth
REGISTRY_NAMESPACE=my-company         # Company namespace
# Result: ghcr.io/my-company/project:tag

# Personal setup
GITHUB_USERNAME=john-doe              # Personal auth and namespace
# Result: ghcr.io/john-doe/project:tag

# Custom registry
REGISTRY=docker.io
REGISTRY_NAMESPACE=myorg
# Result: docker.io/myorg/project:tag
```

### Optional Overrides
```bash
# Auto-detected, but can be explicitly set
CONTAINER_RUNTIME=docker  # or 'podman'
COMPOSE_CMD="docker compose"  # or 'podman-compose'
```

## 📖 Usage Examples

### Development Workflow
```bash
# Environment setup
just env-check                           # Verify container runtime
just registry login                      # Authenticate with registry

# Container management
just container start postgres            # Start PostgreSQL service
just container logs postgres             # View logs
just postgres check                      # Test database connection

# Development operations (with auto-discovery)
just postgres sql "CREATE DATABASE myapp;" # Create development database
just images build                        # Build application image (auto-discovers project and Containerfile)
just images push dev                     # Push development version (auto-discovers project, "dev" as tag)
just images push                         # Push with auto-generated commit tag
```

### Production Deployment
```bash
# Pull latest images (with auto-discovery)
just images pull latest                  # Pull latest version (auto-discovers project)
just images pull postgres 15            # Pull specific PostgreSQL version

# Database operations
just postgres restore latest-backup.sql  # Restore from backup (with confirmation)
just postgres sql "ANALYZE;"             # Optimize database

# Volume management
just volumes list "production_*"         # List production volumes
just volumes clean-all compose.prod.yml  # Clean up old volumes (with confirmation)

# Build and deployment
just images build-all                    # Build all projects with Containerfiles (auto-discovery)
just images info                         # Show image information (auto-discovers project)
```

### Multi-Database Setup
```bash
# PostgreSQL setup
just postgres create-database main_db
just postgres sql "CREATE USER app_user WITH PASSWORD 'secret';" postgres

# MySQL setup
just mysql create-database cache_db
just mysql create-user cache_user secret123 mysql
just mysql grant-privileges cache_db cache_user mysql
```

## 🆕 Migration from Version 1.x

**Breaking Changes in Version 2.0:**

### Command Structure
- **Old**: `just postgres-sql "query"`
- **New**: `just postgres sql "query"`

### Module Declaration
- **Old**: `import 'just-commons/postgres.just'`
- **New**: `mod postgres 'just-commons/postgres'`

### Color Variables
- **Old**: Custom `${GREEN}`, `${RED}` variables
- **New**: Built-in `{{GREEN}}`, `{{RED}}` constants

### Migration Steps
1. Update to Just 1.31.0+
2. Replace `import` statements with `mod` declarations
3. Update command calls to use module syntax
4. Remove custom color variable definitions

## 🤝 Contributing

1. Fork the repository
2. Create feature branch: `git checkout -b feature/new-module`
3. Follow existing module patterns
4. Use modern Just features (groups, confirm, built-in colors)
5. Test across different environments
6. Update documentation
7. Submit pull request

## 📝 License

MIT License - see LICENSE file for details.

## 🔗 Links

- [Just Command Runner](https://just.systems/)
- [Just Documentation](https://just.systems/man/en/)
- [Docker](https://docs.docker.com/)
- [Podman](https://podman.io/)

---

**Just Commons v2.0** - Modern, modular, and maintainable command automation for container-based projects.