# Utility Scripts

This directory contains utility scripts for managing the Shopify AI App Builder.

## Environment File Scripts

### validate-env.sh

Validates `.env` files for common issues including invisible Unicode characters.

**Usage:**
```bash
./scripts/validate-env.sh [env-file-path]

# Examples:
./scripts/validate-env.sh .env
./scripts/validate-env.sh /path/to/custom.env
```

**What it checks:**
- U+200E (Left-to-Right Mark) - the most common issue
- U+200F (Right-to-Left Mark)
- U+200B (Zero Width Space)
- U+FEFF (Byte Order Mark / BOM)
- Other directional formatting characters (U+202A-202E)
- Windows line endings (CRLF)
- Trailing spaces in variable definitions
- Spaces in variable names

**Exit codes:**
- `0` - File is clean
- `1` - Issues found

### clean-env.sh

Removes invisible Unicode characters from `.env` files.

**Usage:**
```bash
./scripts/clean-env.sh [env-file-path]

# Examples:
./scripts/clean-env.sh .env
./scripts/clean-env.sh /path/to/custom.env
```

**What it does:**
- Creates a backup of the original file (`.backup` extension)
- Removes all invisible Unicode characters
- Preserves all valid content

**Always creates a backup** before modifying the file, so you can restore if needed:
```bash
mv .env.backup .env
```

## Typical Workflow

When you encounter Portainer deployment errors with invisible characters:

```bash
# 1. Validate your env file
./scripts/validate-env.sh .env

# 2. If issues found, clean it
./scripts/clean-env.sh .env

# 3. Verify it's fixed
./scripts/validate-env.sh .env

# 4. Deploy to Portainer
```

## Other Scripts

### check-duplicate-classes.php

Comprehensive PHP/WordPress Plugin Static Analyzer that detects runtime errors, duplicate declarations, missing dependencies, and code issues. Optimized for minimal memory usage via streaming token parsing.

**Usage:**
```bash
php scripts/check-duplicate-classes.php /path/to/plugin
php scripts/check-duplicate-classes.php /path/to/plugin --verbose
php scripts/check-duplicate-classes.php /path/to/plugin --quiet
php scripts/check-duplicate-classes.php /path/to/plugin --strict
```

**Options:**
- `--verbose` - Show detailed output and statistics
- `--strict` - Enable stricter checks (may have false positives)
- `--quiet` - Suppress informational messages
- `--no-cache` - Skip caching (useful for CI/CD)

**What it detects:**
- Duplicate class, interface, trait, function, and constant declarations (prevents "Cannot redeclare" errors)
- Missing include/require files
- Usage of undefined classes (new, instanceof, extends, implements, catch)
- **Undefined functions** - Calls to functions that don't exist in the codebase or PHP/WP core
- **Early function calls** - Functions called before they are defined in the same file
- **Potential undefined arrays** - Array accesses on variables that may not be initialized
- **CSS overlap risks** - CSS patterns that may cause UI elements to overlap
- Namespace-aware detection (prevents false positives across namespaces)

**CSS Overlap Detection:**
The script analyzes CSS files for patterns that commonly cause overlapping UI elements:
- Absolute positioned elements at z-index 0
- Elements anchored to both top/bottom or left/right
- Negative margins that can pull elements into overlapping positions

**Exit codes:**
- `0` - No issues found
- `1` - Issues detected

**Example output:**
```
Checking for undefined functions...
  ✓ No undefined functions found

Checking for early function calls...
EARLY FUNCTION CALL: 'my_function' called at line 15 but defined at line 45 in includes/helper.php
    ...
  ✓ No early function calls found

Checking for potential undefined arrays and array keys...
POTENTIAL UNDEFINED ARRAY: '$options' accessed as array at functions.php:23
    This array may not be initialized before use.
    Consider using isset() or !empty() check before access.
    ...

Checking for potential CSS overlaps...
POTENTIAL CSS OVERLAP in admin/css/admin.css:156
    Reason: Negative margin (may cause overlap)
    Context: margin-left: -15px;...
    ...

DUPLICATE CLASS: 'PCFB_Field_Icons' declared in 2 locations:
    admin/class-admin-helper.php:167
    admin/page-form-builder.php:206

MISSING CLASS/TYPE: 'Undefined_Class' used but not declared:
    admin/some-file.php:42 (new)

================================================================================
VALIDATION SUMMARY
================================================================================
Runtime issues (duplicates, missing classes): FOUND
Undefined functions: 0 found
Early function calls: 1 found
Potential undefined arrays: 1 found
Potential CSS overlaps: 1 found

FAIL: Issues detected that should be reviewed
```

### entrypoint.sh

Container entrypoint script that:
- Sets up the environment
- Starts the web server (port 4000)
- Starts the terminal service (port 4001)

This script runs automatically when the Docker container starts. You don't need to run it manually.

### healthcheck.sh

Docker health check script that verifies:
- The web server is responding on port 4000
- The service is healthy

This is used by Docker to monitor container health. You don't need to run it manually.

## Troubleshooting

### Permission denied

If you get "Permission denied" errors:
```bash
chmod +x scripts/*.sh
```

### Command not found

Make sure you're running from the project root:
```bash
cd /path/to/shopify-ai
./scripts/validate-env.sh .env
```

Or use full paths:
```bash
/path/to/shopify-ai/scripts/validate-env.sh /path/to/.env
```