Rustelo/scripts/README.md

# Rustelo Scripts Directory

This directory contains all the utility scripts for the Rustelo framework, organized by category for easy management and maintenance.

## 📁 Directory Structure

```
scripts/
├── databases/          # Database management scripts
├── setup/             # Project setup and installation scripts
├── tools/             # Advanced tooling scripts
├── utils/             # General utility scripts
├── deploy.sh          # Main deployment script
├── install.sh         # Main installation script
└── README.md          # This file
```

## 🚀 Quick Start

### Using Just (Recommended)

The easiest way to use these scripts is through the `justfile` commands:

```bash
# Development
just dev                    # Start development server
just build                  # Build project
just test                   # Run tests

# Database
just db-setup              # Setup database
just db-migrate            # Run migrations
just db-backup             # Create backup

# Tools
just perf-benchmark        # Run performance tests
just security-audit        # Run security audit
just monitor-health        # Monitor application health
just ci-pipeline          # Run CI/CD pipeline
```

### Direct Script Usage

You can also run scripts directly:

```bash
# Database operations
./scripts/databases/db.sh setup create
./scripts/databases/db.sh migrate run

# Performance testing
./scripts/tools/performance.sh benchmark load
./scripts/tools/performance.sh monitor live

# Security scanning
./scripts/tools/security.sh audit full
./scripts/tools/security.sh analyze report

# Monitoring
./scripts/tools/monitoring.sh monitor health
./scripts/tools/monitoring.sh reports generate
```

## 📂 Script Categories

### 🗄️ Database Scripts (`databases/`)

Comprehensive database management and operations:

- **`db.sh`** - Master database management hub
- **`db-setup.sh`** - Database setup and initialization
- **`db-migrate.sh`** - Migration management
- **`db-backup.sh`** - Backup and restore operations
- **`db-monitor.sh`** - Database monitoring and health checks
- **`db-utils.sh`** - Database utilities and maintenance

**Key Features:**
- PostgreSQL and SQLite support
- Automated migrations
- Backup/restore with compression
- Performance monitoring
- Health checks and alerts
- Data export/import
- Schema management

**Usage Examples:**
```bash
# Full database setup
./scripts/databases/db.sh setup setup

# Create backup
./scripts/databases/db.sh backup create

# Monitor database health
./scripts/databases/db.sh monitor health

# Run migrations
./scripts/databases/db.sh migrate run
```

### 🔧 Setup Scripts (`setup/`)

Project initialization and configuration:

- **`install.sh`** - Main installation script
- **`install-dev.sh`** - Development environment setup
- **`setup_dev.sh`** - Development configuration
- **`setup-config.sh`** - Configuration management
- **`setup_encryption.sh`** - Encryption setup

**Key Features:**
- Multi-mode installation (dev/prod/custom)
- Dependency management
- Environment configuration
- Encryption setup
- Feature selection
- Cross-platform support

**Usage Examples:**
```bash
# Basic development setup
./scripts/setup/install.sh

# Production setup with TLS
./scripts/setup/install.sh -m prod --enable-tls

# Custom interactive setup
./scripts/setup/install.sh -m custom
```

### 🛠️ Tool Scripts (`tools/`)

Advanced tooling and automation:

- **`performance.sh`** - Performance testing and monitoring
- **`security.sh`** - Security scanning and auditing
- **`ci.sh`** - CI/CD pipeline management
- **`monitoring.sh`** - Application monitoring and observability

#### Performance Tools (`performance.sh`)

**Commands:**
- `benchmark load` - Load testing
- `benchmark stress` - Stress testing
- `monitor live` - Real-time monitoring
- `analyze report` - Performance analysis
- `optimize build` - Build optimization

**Features:**
- Load and stress testing
- Real-time performance monitoring
- Response time analysis
- Resource usage tracking
- Performance reporting
- Build optimization

**Usage:**
```bash
# Run load test
./scripts/tools/performance.sh benchmark load -d 60 -c 100

# Live monitoring
./scripts/tools/performance.sh monitor live

# Generate report
./scripts/tools/performance.sh analyze report
```

#### Security Tools (`security.sh`)

**Commands:**
- `audit full` - Complete security audit
- `audit dependencies` - Dependency vulnerability scan
- `audit secrets` - Secret scanning
- `analyze report` - Security reporting

**Features:**
- Dependency vulnerability scanning
- Secret detection
- Permission auditing
- Security header analysis
- Configuration security checks
- Automated fixes

**Usage:**
```bash
# Full security audit
./scripts/tools/security.sh audit full

# Scan for secrets
./scripts/tools/security.sh audit secrets

# Fix security issues
./scripts/tools/security.sh audit dependencies --fix
```

#### CI/CD Tools (`ci.sh`)

**Commands:**
- `pipeline run` - Full CI/CD pipeline
- `build docker` - Docker image building
- `test all` - Complete test suite
- `deploy staging` - Staging deployment

**Features:**
- Complete CI/CD pipeline
- Docker image building
- Multi-stage testing
- Quality checks
- Automated deployment
- Build reporting

**Usage:**
```bash
# Run full pipeline
./scripts/tools/ci.sh pipeline run

# Build Docker image
./scripts/tools/ci.sh build docker -t v1.0.0

# Deploy to staging
./scripts/tools/ci.sh deploy staging
```

#### Monitoring Tools (`monitoring.sh`)

**Commands:**
- `monitor health` - Health monitoring
- `monitor metrics` - Metrics collection
- `monitor logs` - Log analysis
- `reports generate` - Monitoring reports

**Features:**
- Real-time health monitoring
- Metrics collection and analysis
- Log monitoring and analysis
- System resource monitoring
- Alert management
- Dashboard generation

**Usage:**
```bash
# Monitor health
./scripts/tools/monitoring.sh monitor health -d 300

# Monitor all metrics
./scripts/tools/monitoring.sh monitor all

# Generate report
./scripts/tools/monitoring.sh reports generate
```

### 🔧 Utility Scripts (`utils/`)

General-purpose utilities:

- **`configure-features.sh`** - Feature configuration
- **`build-examples.sh`** - Example building
- **`generate_certs.sh`** - TLS certificate generation
- **`test_encryption.sh`** - Encryption testing
- **`demo_root_path.sh`** - Demo path generation

## 🚀 Common Workflows

### Development Workflow

```bash
# 1. Initial setup
just setup

# 2. Database setup
just db-setup

# 3. Start development
just dev-full

# 4. Run tests
just test

# 5. Quality checks
just quality
```

### Production Deployment

```bash
# 1. Build and test
just ci-pipeline

# 2. Security audit
just security-audit

# 3. Performance testing
just perf-benchmark

# 4. Deploy to staging
just ci-deploy-staging

# 5. Deploy to production
just ci-deploy-prod
```

### Monitoring and Maintenance

```bash
# 1. Setup monitoring
just monitor-setup

# 2. Health monitoring
just monitor-health

# 3. Performance monitoring
just perf-monitor

# 4. Security monitoring
just security-audit

# 5. Generate reports
just monitor-report
```

## 📋 Script Conventions

### Common Options

Most scripts support these common options:

- `--help` - Show help message
- `--verbose` - Enable verbose output
- `--quiet` - Suppress output
- `--dry-run` - Show what would be done
- `--force` - Skip confirmations
- `--env ENV` - Specify environment

### Exit Codes

Scripts use standard exit codes:

- `0` - Success
- `1` - General error
- `2` - Misuse of shell builtins
- `126` - Command invoked cannot execute
- `127` - Command not found
- `128` - Invalid argument to exit

### Logging

Scripts use consistent logging:

- `[INFO]` - General information
- `[WARN]` - Warnings
- `[ERROR]` - Errors
- `[SUCCESS]` - Success messages
- `[CRITICAL]` - Critical issues

## 🔧 Configuration

### Environment Variables

Scripts respect these environment variables:

```bash
# General
PROJECT_NAME=rustelo
ENVIRONMENT=dev
LOG_LEVEL=info

# Database
DATABASE_URL=postgresql://user:pass@localhost/db

# Docker
DOCKER_REGISTRY=docker.io
DOCKER_IMAGE=rustelo
DOCKER_TAG=latest

# Monitoring
METRICS_PORT=3030
GRAFANA_PORT=3000
PROMETHEUS_PORT=9090
```

### Configuration Files

Scripts may use these configuration files:

- `.env` - Environment variables
- `Cargo.toml` - Rust project configuration
- `package.json` - Node.js dependencies
- `docker-compose.yml` - Docker services

## 🛠️ Development

### Adding New Scripts

1. Create script in appropriate category directory
2. Make executable: `chmod +x script.sh`
3. Add to `justfile` if needed
4. Update this README
5. Add tests if applicable

### Script Template

```bash
#!/bin/bash
# Script Description
# Detailed description of what the script does

set -e

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

# Logging functions
log() { echo -e "${GREEN}[INFO]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }

# Your script logic here
main() {
    log "Starting script..."
    # Implementation
    log "Script completed"
}

# Run main function
main "$@"
```

## 📚 References

- [Just Command Runner](https://just.systems/) - Task runner
- [Bash Style Guide](https://google.github.io/styleguide/shellguide.html) - Shell scripting standards
- [Rustelo Documentation](../README.md) - Main project documentation
- [Docker Documentation](https://docs.docker.com/) - Container management
- [PostgreSQL Documentation](https://www.postgresql.org/docs/) - Database management

## 🆘 Troubleshooting

### Common Issues

1. **Permission Denied**
   ```bash
   chmod +x scripts/path/to/script.sh
   ```

2. **Missing Dependencies**
   ```bash
   just setup-deps
   ```

3. **Environment Variables Not Set**
   ```bash
   cp .env.example .env
   # Edit .env with your values
   ```

4. **Database Connection Issues**
   ```bash
   just db-status
   just db-setup
   ```

5. **Docker Issues**
   ```bash
   docker system prune -f
   just docker-build
   ```

### Getting Help

- Run any script with `--help` for usage information
- Check the `justfile` for available commands
- Review logs in the output directories
- Consult the main project documentation

## 🤝 Contributing

1. Follow the established conventions
2. Add appropriate error handling
3. Include help documentation
4. Test thoroughly
5. Update this README

For questions or issues, please consult the project documentation or create an issue.