sha/just-commons
1
0
Fork 0
mirror of https://github.com/shadoll/just-commons.git synced 2025-12-20 03:26:43 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

🚀 MAJOR: Full migration to Just modules with modern features

Browse Source 
BREAKING CHANGES:
- Complete restructure to Just module architecture (requires Just 1.31.0+)
- Command syntax changed: 'just postgres-sql' → 'just postgres sql'
- Import syntax changed: import → mod declarations

NEW FEATURES:
✨ Module-based architecture with optional modules
✨ Built-in Just colors ({{RED}}, {{GREEN}}, etc.) replace custom variables
✨ Enhanced [confirm] attributes for all destructive operations
✨ Organized [group('name')] attributes for better UX
✨ Modern justfile with comprehensive help system
✨ Updated documentation with migration guide

MODULES:
📦 postgres/    - PostgreSQL operations (sql, check, create-database, etc.)
📦 mysql/       - MySQL operations (sql, check, create-user, etc.)
📦 volumes/     - Volume management (clean-all, remove, list)
📦 container/   - Container operations (start, stop, logs, shell, exec)
📦 registry/    - Registry auth (login, logout, check)
📦 images/      - Image operations (build, push, pull, tag, clean)

USAGE:
just postgres sql "SELECT version();"
just volumes clean-all
just images build myapp

This is Just Commons v2.0 - a complete modernization using all of Just's latest features.
This commit is contained in:
sHa
2025-09-27 02:27:53 +03:00
parent c359858ee9
commit d3fec4b85a
11 changed files with 928 additions and 775 deletions
Download Patch File Download Diff File Expand all files Collapse all files

388
README.md
View File

@@ -1,89 +1,24 @@
# Just Commons
# Just Commons - Universal Command Library
Universal Just command recipes for container management across projects.
**Version 2.0 - Modern Module Architecture**
## Overview
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.
This repository contains reusable Just recipes for:
- **Container operations**: start, stop, restart, logs, shell, exec, status
- **Registry authentication**: login, logout, status checks for GitHub Container Registry
- **Image operations**: build, push, pull, tag, test, info, clean
- **Database operations**: PostgreSQL and MySQL database management
## 🚀 Features
## Usage
- **🎯 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
Add as a Git submodule to your project:
```bash
git submodule add git@github.com:shadoll/just-commons.git
```
Import in your `justfile`:
```bash
# Import universal commands
import 'just-commons/core.just' # Core utilities
import 'just-commons/container.just' # Container operations
import 'just-commons/registry.just' # Registry authentication
import 'just-commons/images.just' # Image operations
# Import database and volume commands (optional)
import 'just-commons/postgres.just' # PostgreSQL operations
import 'just-commons/mysql.just' # MySQL operations
import 'just-commons/volumes.just' # Volume management
```
## Files
### Core Files
- `core.just` - Core utilities (_detect_runtime, _detect_compose, env-check)
- `container.just` - Universal container operations (start, stop, logs, shell, exec, status)
- `registry.just` - GitHub Container Registry authentication (registry-login, registry-logout, registry-check)
- `images.just` - Universal image operations (image-build, image-push, image-pull, image-tag, etc.)
### Database Files (Optional)
- `postgres.just` - PostgreSQL operations (postgres-sql, postgres-check, postgres-list-databases, etc.)
- `mysql.just` - MySQL operations (mysql-sql, mysql-check, mysql-list-databases, etc.)
### Volume Management (Optional)
- `volumes.just` - Volume operations (volumes-clean-all, volumes-remove, volumes-list, etc.)
### Command Structure
- **Container commands**: No prefix (start, stop, logs, shell, exec, status, restart)
- **All other commands**: Prefixed by file type (image-*, registry-*, postgres-*, mysql-*)
### Usage Examples
```bash
# Container operations (no prefix)
just start postgres
just logs postgres
just shell postgres
# Image operations (image- prefix)
just image-build postgres
just image-push postgres v1.0.0
# Registry operations (registry- prefix)
just registry-login
just registry-check
# Database operations (database- prefix)
just postgres-sql "SELECT version();"
just postgres-check
just mysql-sql "SELECT VERSION();"
# Volume operations (volumes- prefix)
just volumes-list "myproject_*"
just volumes-clean-all
just volumes-remove "old_volume"
```
## Requirements
## 📋 Requirements
### Just Command Runner
This library requires **Just 1.14.0 or later** to support the `group` attribute for organized command display.
This library requires **Just 1.31.0 or later** for module support and modern features.
#### Installation on Ubuntu 24.04 LTS
@@ -107,6 +42,303 @@ chmod +x /usr/local/bin/just
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 automatic registry detection**
```bash
just images build <project> [tag] # Build project image
just images push <project> [tag] # Push image to registry
just images pull <project> [tag] # Pull image from registry
just images tag <project> <new-tag> # Tag existing image
just images info <project> [tag] # Show image information
just images clean <project> # Remove project images (with confirmation)
just images build-all # Build all projects with Containerfiles
```
### 🔐 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 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
```
## 🎨 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
### Required for Registry Operations
```bash
# .env file
GITHUB_USERNAME=your-username
GITHUB_TOKEN=ghp_your-token
REGISTRY=ghcr.io
```
### 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
just postgres sql "CREATE DATABASE myapp;" # Create development database
just images build myapp # Build application image
just images push myapp dev # Push development version
```
### Production Deployment
```bash
# Pull latest images
just images pull myapp latest
just images pull postgres 15
# 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)
```
### 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.