.cursorrules

# Scaffold Toolkit Installer Script

1. Core Features
	-	Interactive Prompts:
	-	Prompt users to select:
	1.	Scaffold Type:
		- DrevOps (available)
		- Vortex (coming soon)
		- GovCMS PaaS (coming soon)
	2.	CI/CD Integration:
		- CircleCI (available)
		- GitHub Actions (coming soon)
	2.1. SSH Key MD5 Hash (if CircleCI selected)
	3.	Hosting Environment:
		- Lagoon
		- Acquia
	4.	Scripts and .twig_cs.php Update
	5.	Final Review of Changes
	6.	Installation Summary
	-	File-specific questions will include:
	-	Whether to override an existing file based on detected version differences.
	-	Initial installations will provide contextual prompts if version metadata is missing.
	-	Versioning Metadata:
	-	All scaffold files will include metadata such as:
    ```
    # Version: 1.0.0
    # Customized: false
    ```

2. Installation Process
   - Source Directory Handling:
     - Files are pulled from GitHub by default
     - Local files used only for testing (with --use-local-files)
     - Target directory for installations can be specified (default: '.')
     - Directory structure is automatically created
   
   - File Processing:
     - Version checking for existing files
     - Non-interactive mode for automated installations
     - Proper error handling and reporting
     - GitHub download error handling
     - Automatic execute permissions for .sh files

3. Testing Environment
   - Docker-based Testing:
     - Uses Lagoon PHP 8.3 CLI image
     - Source code is copied to /source during build
     - Tests run in /workspace directory
     - Each test gets a clean environment
     - Uses local files instead of GitHub

   - Test Matrix:
     - Scaffold Types:
       - DrevOps (available)
       - Vortex (coming soon)
       - GovCMS PaaS (coming soon)
     - CI/CD Types:
       - CircleCI (available)
       - GitHub Actions (coming soon)
     - Hosting Types:
       - Lagoon
       - Acquia
     - Installation Types:
       - Normal installation
       - Force installation

   - Test Process:
     - Clean environment before each test
     - Run installation with --use-local-files
     - Show directory contents
     - Clean up after test
     - Colored output for pass/fail status

4. Project Structure
   ```
   .
   ├── ci/
   │   ├── circleci/               # CircleCI configuration
   │   │   ├── acquia/            # Acquia-specific config
   │   │   └── lagoon/            # Lagoon-specific config
   │   └── gha/                   # GitHub Actions (coming soon)
   │       ├── acquia/            # Acquia-specific config
   │       └── lagoon/            # Lagoon-specific config
   ├── scripts/                   # Scripts directory
   ├── renovatebot/
   │   ├── drupal/                # Drupal-specific Renovate config
   │   │   └── renovate.json
   │   └── govcms_paas/          # GovCMS PaaS Renovate config
   │       └── renovate.json
   ├── scaffold-installer.php     # Main installer script
   ├── Dockerfile.test           # Testing environment setup
   ├── docker-compose.test.yml   # Docker Compose configuration
   └── .ahoy.yml                 # Ahoy commands for testing
   ```

5. Command Line Options
   ```bash
   php scaffold-installer.php [options]
   
   Options:
   --scaffold=<type>      Select scaffold type (drevops|vortex|govcms)
   --latest              Use latest version
   --version=<tag>       Use specific version
   --force               Overwrite existing files
   --ci=<type>          Select CI/CD type (circleci|github)
   --hosting=<type>     Select hosting (lagoon|acquia)
   --source-dir=<path>  Source directory for files
   --target-dir=<path>  Target directory for installation
   --non-interactive    Run without prompts
   --use-local-files    Use local files instead of GitHub
   --github-repo        Custom GitHub repository
   --github-branch      Custom GitHub branch
   --distribution       Distribution type (drupal|govcms_paas)
   --ssh-fingerprint    SSH key fingerprint for CircleCI
   ```

6. Testing Commands
   ```bash
   # Start testing environment
   ahoy up

   # Run all tests
   ahoy test

   # Stop and clean environment
   ahoy down
   ```

7. Test Output Format
   ```
   Running test: Install - drevops with circleci and lagoon
   ✓ Test passed: Install - drevops with circleci and lagoon

   Test directory contents for Install - drevops with circleci and lagoon:
   .circleci/
   └── config.yml
   renovate.json
   ```

8. Error Handling
   - Proper error messages for missing files
   - Validation of source and target directories
   - Exit codes for test failures
   - Colored output for errors and successes
   - GitHub download error handling
   - cURL error handling for GitHub requests

9. Development Guidelines
   - Keep source files versioned
   - Add tests for new features
   - Clean up test environment between runs
   - Use non-interactive mode for CI/CD
   - Follow Drupal coding standards
   - Test both GitHub and local file modes

# File version tracking
Aleays increment version in the installer script and in this file.
scaffold-installer.php=1.0.16