shopify-ai-backup/scripts/README.md

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:

./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:

./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:

mv .env.backup .env

Typical Workflow

When you encounter Portainer deployment errors with invisible characters:

# 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:

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:

chmod +x scripts/*.sh

Command not found

Make sure you're running from the project root:

cd /path/to/shopify-ai
./scripts/validate-env.sh .env

Or use full paths:

/path/to/shopify-ai/scripts/validate-env.sh /path/to/.env