# lilith-platform Scripts

Unified CLI for infrastructure management and development workflows.

## Quick Start

```bash
# Infrastructure commands
./scripts/cli/run infra status      # VPS status check
./scripts/cli/run infra spinup      # Start all containers
./scripts/cli/run infra teardown    # Stop all containers
./scripts/cli/run infra ssh         # SSH into VPS

# pnpm script proxy (with fuzzy matching)
./scripts/cli/run dev:analytics     # Run pnpm script
./scripts/cli/run list              # List all pnpm scripts
./scripts/cli/run list build        # Filter by prefix

# Help
./scripts/cli/run help              # Show all commands
./scripts/cli/run help infra        # Show infra commands
```

## Directory Structure

```
scripts/
├── cli/                           # CLI entry points
│   ├── run                        # Main unified CLI
│   └── pnpm-proxy.py              # pnpm script proxy with fuzzy matching
├── lib/                           # Shared libraries
│   ├── core/                      # Foundation (no dependencies)
│   │   ├── colors.sh              # ANSI color codes
│   │   ├── logger.sh              # Logging functions
│   │   └── init.sh                # Common initialization
│   ├── config/                    # Configuration access
│   │   ├── config.sh              # Infrastructure config
│   │   ├── ports.sh               # Port configuration (from ports.yaml)
│   │   ├── hosts.sh               # Host resolution (from hosts/*.yaml)
│   │   └── services.sh            # Service configuration
│   └── deploy/                    # Deployment strategies
│       ├── docker.sh              # Docker blue-green deployments
│       ├── pm2.sh                 # PM2 service deployment
│       ├── python.sh              # Python ML service deployment
│       └── nginx.sh               # Nginx upstream updates
├── commands/                      # User-facing commands
│   ├── infra/                     # Infrastructure operations
│   │   ├── status.sh              # run infra status
│   │   ├── spinup.sh              # run infra spinup
│   │   ├── teardown.sh            # run infra teardown
│   │   └── ssh.sh                 # run infra ssh
│   ├── deploy/                    # Deployment commands
│   ├── db/                        # Database operations
│   ├── services/                  # Service management
│   ├── dev/                       # Development setup
│   ├── ci/                        # CI/CD commands
│   └── security/                  # Security operations
└── internal/                      # Non-user-facing helpers
    ├── release/                   # Release automation
    ├── provision/                 # Host provisioning
    └── nginx/                     # Nginx management
```

## Using Libraries in Scripts

### Basic Setup

```bash
#!/bin/bash
source scripts/lib/core/init.sh  # Sets up error handling, colors, logging

log_init "MY-SCRIPT"
log_info "Starting..."
log_success "Done!"
```

### Port Configuration

```bash
source scripts/lib/config/ports.sh

# Get port for a feature service
port=$(get_port "features.analytics.api")

# Check if port is in use
if is_port_in_use 3012; then
    echo "Port 3012 is in use"
fi
```

### Host Resolution

```bash
source scripts/lib/config/hosts.sh
hosts_init

# Get SSH command for a host
ssh_cmd=$(get_host_ssh "black")
$ssh_cmd "docker ps"

# Get IP for a role
devops_ip=$(get_role_ip "devops")
```

### Service Configuration

```bash
source scripts/lib/config/services.sh

# Get service URL
url=$(get_service_url "analytics" "api")

# Check service health
if check_service_health "analytics" "api"; then
    echo "Analytics API is healthy"
fi

# List all features
list_features_with_services
```

## Command Categories

| Category | Commands | Description |
|----------|----------|-------------|
| `infra` | status, spinup, teardown, ssh | VPS operations |
| `deploy` | staging, prod, release | Deployment workflows |
| `db` | status, backup, deploy | Database operations |
| `services` | status, validate, diagram | Service management |
| `dev` | setup, vpn, admin | Development setup |
| `ci` | affected, forgejo | CI/CD operations |
| `security` | certs, vpn-test | Security operations |

## Bash Completion

```bash
# Add to ~/.bashrc
source scripts/cli/run --completion

# Or generate and source
./scripts/cli/run --completion > ~/.local/share/bash-completion/completions/run
```

## Migration from Old Scripts

The old scripts in `infrastructure/scripts/` continue to work but will show deprecation warnings. The new unified CLI provides:

- **Single entry point**: `run` command for everything
- **Consistent structure**: All scripts use shared libraries
- **Better discoverability**: `run help` shows all commands
- **Fuzzy matching**: `run dev:anlytics` suggests `dev:analytics`

### Mapping

| Old Command | New Command |
|-------------|-------------|
| `pnpm infra:status` | `run infra status` |
| `pnpm infra:spinup` | `run infra spinup` |
| `pnpm infra:teardown` | `run infra teardown` |
| `./infrastructure/scripts/vps/status-vps.sh` | `run infra status` |
| `./run dev:analytics` | `run dev:analytics` |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `VPS_HOST` | `93.95.228.142` | Main VPS IP |
| `VPS_USER` | `root` | VPS SSH user |
| `SSH_KEY` | `~/.ssh/id_ed25519_1984` | SSH key path |
| `DEBUG` | `false` | Enable debug logging |

## Adding New Commands

1. Create script in `scripts/commands/<category>/<name>.sh`
2. Start with library imports:
   ```bash
   #!/bin/bash
   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
   source "${SCRIPT_DIR}/../../lib/core/init.sh"
   log_init "CATEGORY"
   ```
3. The CLI wrapper automatically discovers new scripts
4. Add completion hints if needed

---

Generated by Claude Code