From 102f9d7eff0a9af84c361a6257faed4062b4367b Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Thu, 4 Sep 2025 17:02:54 +1000 Subject: [PATCH] Updated AI instructions. --- .vortex/CLAUDE.md | 69 +- .../install/ai_instructions_claude/CLAUDE.md | 688 ++++++++++++---- .../install/ciprovider_circleci/CLAUDE.md | 688 ++++++++++++---- .../Fixtures/install/ciprovider_gha/CLAUDE.md | 688 ++++++++++++---- .../CLAUDE.md | 688 ++++++++++++---- .../Fixtures/install/hosting_acquia/CLAUDE.md | 692 +++++++++++++---- .../Fixtures/install/hosting_lagoon/CLAUDE.md | 692 +++++++++++++---- .../provision_database_lagoon/CLAUDE.md | 692 +++++++++++++---- .../install/provision_profile/CLAUDE.md | 688 ++++++++++++---- .../install/services_no_clamav/CLAUDE.md | 679 ++++++++++++---- .../install/services_no_solr/CLAUDE.md | 674 ++++++++++++---- .../install/services_no_valkey/CLAUDE.md | 677 ++++++++++++---- .../Fixtures/install/theme_absent/CLAUDE.md | 667 ++++++++++++---- .vortex/tests/lint.markdown.sh | 2 + CLAUDE.md | 734 +++++++++++++----- 15 files changed, 6801 insertions(+), 2217 deletions(-) diff --git a/.vortex/CLAUDE.md b/.vortex/CLAUDE.md index 99d7f8bc4..d3fcf5521 100644 --- a/.vortex/CLAUDE.md +++ b/.vortex/CLAUDE.md @@ -10,7 +10,7 @@ ### Project Structure -``` +```text vortex/ ├── .vortex/ # Test harness and development tools │ ├── docs/ # Documentation for Vortex @@ -26,6 +26,7 @@ vortex/ ## .vortex Directory Structure ### .vortex/docs/ + - **Docusaurus-based documentation** published to https://www.vortextemplate.com - **MDX content system** with interactive components - **Multi-layered testing**: Jest (unit), E2E, and spellcheck validation @@ -33,17 +34,20 @@ vortex/ - **Custom React components** for enhanced documentation UX ### .vortex/installer/ + - Self-contained Symfony console application - Handles Vortex installation and customization - **Fixture System**: Uses baseline + diff architecture ### .vortex/tests/ + - Unit and functional tests for Vortex - Uses both **PHPUnit** (functional workflows) and **BATS** (shell script unit tests) ## Testing Framework ### Documentation Testing (.vortex/docs/) + - **Jest-based testing** with jsdom and React Testing Library - **Unit tests**: React component functionality and interactions - **Spellcheck**: cspell validation for American English consistency @@ -51,6 +55,7 @@ vortex/ - **Location**: `tests/unit/` ### PHPUnit Tests (.vortex/tests/phpunit/) + - **Purpose**: Functional testing of Vortex user workflows - **Scope**: Processes and commands in context of Vortex installation - **Location**: `.vortex/tests/phpunit/` @@ -59,6 +64,7 @@ vortex/ - `Functional/FunctionalTestCase.php` - Base test case ### BATS Tests (.vortex/tests/bats/) + - **Purpose**: Unit testing of shell scripts with coverage - **Technology**: [Bats (Bash Automated Testing System)](https://github.com/bats-core/bats-core) - **Location**: `.vortex/tests/bats/` @@ -68,9 +74,11 @@ vortex/ - `fixtures/` - Test fixture files #### BATS Helpers System + The BATS tests use a sophisticated helper system located in `node_modules/bats-helpers/src/steps.bash` that provides: **Step Types**: + 1. **Command Mocking**: `@ [] # [ # ]` - Mocks shell commands with specific exit codes and output - Example: `"@drush -y status --field=drupal-version # mocked_core_version"` @@ -85,6 +93,7 @@ The BATS tests use a sophisticated helper system located in `node_modules/bats-h - Example: `"- Existing database detected. Performing additional example operations."` **Usage Pattern**: + ```bash declare -a STEPS=( "@drush -y status # 0 # success" # Mock command @@ -100,6 +109,7 @@ run_steps "assert" "${mocks}" # Assert phase ### Running Tests **Documentation Tests** (`.vortex/docs/`): + ```bash cd .vortex/docs @@ -124,6 +134,7 @@ yarn lint-fix ``` **Template Tests** (`.vortex/`): + ```bash cd .vortex @@ -146,13 +157,15 @@ bats tests/bats/unit/notify.bats ## Installer Fixture System ### Architecture + The installer uses a **baseline + diff** system for managing test fixtures: 1. **Baseline** (`_baseline/`): Complete template files 2. **Scenario Fixtures**: Diff files that modify the baseline ### Fixture Locations -``` + +```text .vortex/installer/tests/Fixtures/install/ ├── _baseline/ # Complete template files ├── services_no_clamav/ # Diff: removes ClamAV-related content @@ -180,12 +193,14 @@ UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter 'testInstall.*"services.*no.*cla ``` **How it works**: + 1. Tests run and compare actual output vs expected fixtures 2. When `UPDATE_FIXTURES=1` is set, differences automatically update fixtures 3. Baseline changes propagate to all scenario diffs 4. Each scenario maintains only its differences from baseline ### Fixture Update Process + 1. **Baseline First**: Update baseline fixtures first 2. **Scenario Diffs**: Run individual scenario tests to update their diffs 3. **Validation**: Verify tests pass without UPDATE_FIXTURES flag @@ -193,6 +208,7 @@ UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter 'testInstall.*"services.*no.*cla ## Script Output Formatters ### Standard Output Formatters + Vortex uses consistent output formatting across all scripts: ```bash @@ -207,6 +223,7 @@ note() { printf " %s\n" "${1}"; } ``` ### Usage Guidelines + - **info()**: Main section headers and completion messages - **pass()**: Success confirmations - **fail()**: Error messages @@ -214,6 +231,7 @@ note() { printf " %s\n" "${1}"; } - **note()**: Conditional messages, details, hints ### Example Usage + ```bash info "Executing example operations in non-production environment." task "Setting site name." @@ -233,6 +251,7 @@ info "Finished executing example operations in non-production environment." ### Provision Script BATS Test Logic The provision example script (`scripts/custom/provision-10-example.sh`) uses conditional logic: + ```bash if [ "${VORTEX_PROVISION_OVERRIDE_DB:-0}" = "1" ]; then note "Fresh database detected. Performing additional example operations." @@ -242,6 +261,7 @@ fi ``` **BATS Test Expectations**: + - **Fresh database scenarios**: Should have "Fresh database detected" and NOT have "Existing database detected" - `"Provision: DB; no site"` - `"Provision: DB; existing site; overwrite"` @@ -254,6 +274,7 @@ fi - `"Provision: profile; existing site"` **Test Pattern**: + ```bash # Fresh database tests " Fresh database detected. Performing additional example operations." @@ -265,6 +286,7 @@ fi ``` ### BATS Test Updates + When script output changes, update corresponding test files: ```bash @@ -279,6 +301,7 @@ When script output changes, update corresponding test files: ### Common Test Commands **Documentation Workflow** (`.vortex/docs/`): + ```bash # Development workflow yarn start # Start dev server @@ -292,6 +315,7 @@ yarn test:watch # Watch mode for development ``` **Template Testing** (`.vortex/`): + ```bash # From .vortex/ ahoy install # Install all dependencies @@ -313,22 +337,26 @@ ahoy test-bats -- tests/bats/ # All BATS tests ## Environment Variables ### Testing + - `TEST_VORTEX_DEBUG=1` - Enable debug output - `TEST_NODE_INDEX` - CI runner index for parallel execution - `VORTEX_DEV_TEST_COVERAGE_DIR` - Coverage output directory - `UPDATE_FIXTURES=1` - Enable fixture updates during tests ### Development + - `VORTEX_DEBUG=1` - Enable debug mode in scripts ## Conditional Token System ### Overview + Vortex uses conditional tokens to strip out content from template files based on user selections during installation. This allows the same template to generate customized projects with only relevant features. ### Token Patterns **Markdown files** (like `README.dist.md`, `CLAUDE.md`): + ```markdown [//]: # (#;< TOKEN_NAME) Content that gets removed if user doesn't select this feature @@ -336,6 +364,7 @@ Content that gets removed if user doesn't select this feature ``` **Shell/YAML files** (like `docker-compose.yml`, shell scripts): + ```bash #;< TOKEN_NAME Content that gets removed if user doesn't select this feature @@ -345,42 +374,52 @@ Content that gets removed if user doesn't select this feature ### Available Tokens **Theme-related**: + - `DRUPAL_THEME` - Custom theme functionality **Services**: + - `SERVICE_CLAMAV` - ClamAV virus scanning - `SERVICE_SOLR` - Solr search engine - `SERVICE_VALKEY` - Valkey/Redis caching **CI Providers**: + - `CI_PROVIDER_GHA` - GitHub Actions - `CI_PROVIDER_CIRCLECI` - CircleCI - `CI_PROVIDER_ANY` - Any CI provider selected **Hosting Providers**: + - `HOSTING_LAGOON` - Lagoon hosting - `HOSTING_ACQUIA` - Acquia hosting **Deployment Types**: + - `DEPLOY_TYPE_CONTAINER_REGISTRY` - Container registry deployments - `DEPLOY_TYPE_WEBHOOK` - Webhook deployments - `DEPLOY_TYPE_ARTIFACT` - Artifact deployments **Dependencies**: + - `DEPS_UPDATE_PROVIDER` - Automated dependency updates (RenovateBot) **Database**: + - `!DB_DOWNLOAD_SOURCE_NONE` - Negated token, removes content when NO database download source is selected **Documentation**: + - `DOCS_ONBOARDING` - Onboarding documentation sections **Provisioning**: + - `!PROVISION_TYPE_PROFILE` - Negated token for non-profile provision types ### Token Implementation Locations **Handler Classes** (`.vortex/installer/src/Prompts/Handlers/`): + - `CiProvider.php` - Defines CI_PROVIDER_* tokens - `HostingProvider.php` - Defines HOSTING_* tokens - `Services.php` - Defines SERVICE_* tokens @@ -388,6 +427,7 @@ Content that gets removed if user doesn't select this feature - `DependencyUpdatesProvider.php` - Defines DEPS_UPDATE_PROVIDER token **Token Processing** (`.vortex/installer/src/Prompts/Handlers/Internal.php:29`): + ```php // Remove all conditional tokens during installation File::removeTokenInDir($this->tmpDir); @@ -405,6 +445,7 @@ When creating or updating template files: ### Example Usage in Template Files **Root CLAUDE.md** - Wrapping theme-specific content: + ```markdown [//]: # (#;< DRUPAL_THEME) @@ -415,6 +456,7 @@ Commands and workflows for custom theme development... ``` **docker-compose.yml** - Service-specific containers: + ```yaml #;< SERVICE_SOLR solr: @@ -434,6 +476,7 @@ When adding new conditional features: ### Token Testing Conditional tokens are tested through the installer fixture system: + - **Baseline fixtures** contain all possible content - **Scenario fixtures** show what gets removed for specific configurations - Use `UPDATE_FIXTURES=1` mechanism to regenerate after token changes @@ -441,7 +484,8 @@ Conditional tokens are tested through the installer fixture system: ## Key Directories and Files ### Template Structure (Outside .vortex/) -``` + +```text ├── scripts/ │ ├── vortex/ # Core Vortex scripts │ └── custom/ # Custom project scripts @@ -455,7 +499,8 @@ Conditional tokens are tested through the installer fixture system: ``` ### Test Harness (.vortex/) -``` + +```text ├── docs/ # Vortex documentation (Docusaurus) │ ├── src/components/ # React components (VerticalTabs, etc.) │ ├── tests/unit/ # Jest tests @@ -474,17 +519,20 @@ Conditional tokens are tested through the installer fixture system: ## Maintenance Tips ### Fixture Updates Can Be Finicky + - The `UPDATE_FIXTURES=1` mechanism can have defects - Try updating baseline first, then individual scenarios - Use filtered test runs for specific scenarios - Be patient - full test suite can take several minutes ### Script Changes Require Multi-Level Updates + 1. **Main script** (template level) 2. **BATS test assertions** (unit test level) 3. **Installer fixtures** (integration test level) ### Output Formatter Consistency + - Always use the standard formatter functions - Maintain consistent output patterns across all scripts - Test changes with both BATS and installer fixture tests @@ -492,6 +540,7 @@ Conditional tokens are tested through the installer fixture system: ## Troubleshooting ### Fixture Update Issues + ```bash # Try baseline first UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter "testInstall.*baseline" @@ -504,11 +553,13 @@ UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter 'testInstall.*"scenario_name"' ``` ### Test Failures + - Check BATS test output formatting matches script changes - Verify installer fixtures are properly updated - Ensure output formatters are defined in all scripts ### Performance + - BATS tests are fast (unit level) - PHPUnit workflow tests are slower (integration level) - Installer tests are slowest (full installation simulation) @@ -520,6 +571,7 @@ UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter 'testInstall.*"scenario_name"' **Batch Processing Pattern**: The installer uses batch processing for file operations to improve performance. All file modifications are queued and executed in a single pass through the directory tree. **Key Pattern**: + ```php // Before: Individual operations (slow) File::replaceContentInFile($file, 'old', 'new'); @@ -565,9 +617,9 @@ File::runTaskDirectory($this->config->get(Config::TMP)); ### Refactoring Workflow -2. **Create Wrappers**: Add static methods to `File` class for common patterns -3. **Replace Usage**: Update handlers to use wrapper methods -4. **Test Systematically**: +1. **Create Wrappers**: Add static methods to `File` class for common patterns +1. **Replace Usage**: Update handlers to use wrapper methods +1. **Test Systematically**: - Run baseline test first to verify core functionality - Run individual test scenarios to catch edge cases - Use `UPDATE_FIXTURES=1` to regenerate expected outputs when needed @@ -575,6 +627,7 @@ File::runTaskDirectory($this->config->get(Config::TMP)); ### Performance Insights **Critical Success Factors**: + - Maintain execution order (handlers queue, PromptManager executes) - Preserve complex logic in callbacks for edge cases (e.g., empty line processing exclusions) - Test each handler type (token removal, string replacement, custom transformation) @@ -593,6 +646,7 @@ File::runTaskDirectory($this->config->get(Config::TMP)); The installer tests have been refactored to use a modular, handler-focused architecture that improves maintainability and test execution flexibility. **Abstract Base Class**: `AbstractInstallTestCase` provides shared test logic for all installer test scenarios, including: + - Common setup and teardown procedures - Core `testInstall()` method with data provider integration - Fixture management and assertion helpers @@ -606,6 +660,7 @@ The installer tests have been refactored to use a modular, handler-focused archi - **Scalable Architecture**: Easy to add new handler tests following established patterns **Key Benefits**: + - Run all handler tests: `--filter "Handlers\\\\"` - Run specific handler: `--filter "HandlerNameInstallTest"` - Run specific scenarios: `--filter "HandlerNameInstallTest.*scenario_pattern"` diff --git a/.vortex/installer/tests/Fixtures/install/ai_instructions_claude/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/ai_instructions_claude/CLAUDE.md index b8e54f85d..57062f926 100644 --- a/.vortex/installer/tests/Fixtures/install/ai_instructions_claude/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/ai_instructions_claude/CLAUDE.md @@ -1,330 +1,680 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod ``` -## Database and Content +## PHP Script Execution (IMPORTANT) -### Content Management +### ✅ Correct Way: Use PHP Scripts -- Use Configuration Management for structure (content types, fields, views) -- Use database imports for content in non-production environments -- Use migration modules for structured content imports in production +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name -## Services Integration +# List available scripts +ahoy drush php:script -### Solr Search +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 +``` + +### ❌ NEVER Do This ```bash -# Check Solr status +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); + +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations + +### Solr Search Service + +```bash +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **GitHub Actions** for CI/CD - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging -### Common Issues +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` + +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/ciprovider_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/ciprovider_circleci/CLAUDE.md index 69859013a..a85e11b34 100644 --- a/.vortex/installer/tests/Fixtures/install/ciprovider_circleci/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/ciprovider_circleci/CLAUDE.md @@ -1,330 +1,680 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod ``` -## Database and Content +## PHP Script Execution (IMPORTANT) -### Content Management +### ✅ Correct Way: Use PHP Scripts -- Use Configuration Management for structure (content types, fields, views) -- Use database imports for content in non-production environments -- Use migration modules for structured content imports in production +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name -## Services Integration +# List available scripts +ahoy drush php:script -### Solr Search +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 +``` + +### ❌ NEVER Do This ```bash -# Check Solr status +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); + +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations + +### Solr Search Service + +```bash +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **CircleCI** for CI/CD - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging -### Common Issues +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` + +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **CircleCI** - See `.circleci/config.yml` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/ciprovider_gha/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/ciprovider_gha/CLAUDE.md index b8e54f85d..57062f926 100644 --- a/.vortex/installer/tests/Fixtures/install/ciprovider_gha/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/ciprovider_gha/CLAUDE.md @@ -1,330 +1,680 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod ``` -## Database and Content +## PHP Script Execution (IMPORTANT) -### Content Management +### ✅ Correct Way: Use PHP Scripts -- Use Configuration Management for structure (content types, fields, views) -- Use database imports for content in non-production environments -- Use migration modules for structured content imports in production +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name -## Services Integration +# List available scripts +ahoy drush php:script -### Solr Search +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 +``` + +### ❌ NEVER Do This ```bash -# Check Solr status +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); + +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations + +### Solr Search Service + +```bash +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **GitHub Actions** for CI/CD - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging -### Common Issues +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` + +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/db_download_source_container_registry/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/db_download_source_container_registry/CLAUDE.md index b8e54f85d..57062f926 100644 --- a/.vortex/installer/tests/Fixtures/install/db_download_source_container_registry/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/db_download_source_container_registry/CLAUDE.md @@ -1,330 +1,680 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod ``` -## Database and Content +## PHP Script Execution (IMPORTANT) -### Content Management +### ✅ Correct Way: Use PHP Scripts -- Use Configuration Management for structure (content types, fields, views) -- Use database imports for content in non-production environments -- Use migration modules for structured content imports in production +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name -## Services Integration +# List available scripts +ahoy drush php:script -### Solr Search +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 +``` + +### ❌ NEVER Do This ```bash -# Check Solr status +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); + +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations + +### Solr Search Service + +```bash +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **GitHub Actions** for CI/CD - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging -### Common Issues +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` + +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/hosting_acquia/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/hosting_acquia/CLAUDE.md index 39d07dce4..9a9a755bf 100644 --- a/.vortex/installer/tests/Fixtures/install/hosting_acquia/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/hosting_acquia/CLAUDE.md @@ -1,332 +1,682 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── docroot/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── docroot/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: docroot/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd docroot/themes/custom/star_wars +cd docroot/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod +``` + +## PHP Script Execution (IMPORTANT) + +### ✅ Correct Way: Use PHP Scripts + +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name + +# List available scripts +ahoy drush php:script + +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 ``` -## Database and Content +### ❌ NEVER Do This + +```bash +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); -## Services Integration +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations -### Solr Search +### Solr Search Service ```bash -# Check Solr status +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **GitHub Actions** for CI/CD - -- **Acquia** for hosting - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd docroot/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd docroot/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status +``` + +### Container Debugging + +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal ``` -## Troubleshooting +### Common Issues & Solutions -### Common Issues +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Acquia Cloud** - Enterprise Drupal hosting + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/hosting_lagoon/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/hosting_lagoon/CLAUDE.md index bf7588396..f65dfec22 100644 --- a/.vortex/installer/tests/Fixtures/install/hosting_lagoon/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/hosting_lagoon/CLAUDE.md @@ -1,332 +1,682 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod +``` + +## PHP Script Execution (IMPORTANT) + +### ✅ Correct Way: Use PHP Scripts + +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name + +# List available scripts +ahoy drush php:script + +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 ``` -## Database and Content +### ❌ NEVER Do This + +```bash +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); -## Services Integration +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations -### Solr Search +### Solr Search Service ```bash -# Check Solr status +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **GitHub Actions** for CI/CD - -- **Lagoon** for hosting - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status +``` + +### Container Debugging + +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal ``` -## Troubleshooting +### Common Issues & Solutions -### Common Issues +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Lagoon** - Container-based hosting platform + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/provision_database_lagoon/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/provision_database_lagoon/CLAUDE.md index bf7588396..f65dfec22 100644 --- a/.vortex/installer/tests/Fixtures/install/provision_database_lagoon/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/provision_database_lagoon/CLAUDE.md @@ -1,332 +1,682 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod +``` + +## PHP Script Execution (IMPORTANT) + +### ✅ Correct Way: Use PHP Scripts + +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name + +# List available scripts +ahoy drush php:script + +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 ``` -## Database and Content +### ❌ NEVER Do This + +```bash +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); -## Services Integration +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations -### Solr Search +### Solr Search Service ```bash -# Check Solr status +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **GitHub Actions** for CI/CD - -- **Lagoon** for hosting - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status +``` + +### Container Debugging + +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal ``` -## Troubleshooting +### Common Issues & Solutions -### Common Issues +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Lagoon** - Container-based hosting platform + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/provision_profile/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/provision_profile/CLAUDE.md index b8e54f85d..57062f926 100644 --- a/.vortex/installer/tests/Fixtures/install/provision_profile/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/provision_profile/CLAUDE.md @@ -1,330 +1,680 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod ``` -## Database and Content +## PHP Script Execution (IMPORTANT) -### Content Management +### ✅ Correct Way: Use PHP Scripts -- Use Configuration Management for structure (content types, fields, views) -- Use database imports for content in non-production environments -- Use migration modules for structured content imports in production +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name -## Services Integration +# List available scripts +ahoy drush php:script -### Solr Search +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 +``` + +### ❌ NEVER Do This ```bash -# Check Solr status +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); + +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations + +### Solr Search Service + +```bash +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **GitHub Actions** for CI/CD - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging -### Common Issues +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` + +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/services_no_clamav/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/services_no_clamav/CLAUDE.md index 5f60deea9..d7d337076 100644 --- a/.vortex/installer/tests/Fixtures/install/services_no_clamav/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/services_no_clamav/CLAUDE.md @@ -1,320 +1,667 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod +``` + +## PHP Script Execution (IMPORTANT) + +### ✅ Correct Way: Use PHP Scripts + +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name + +# List available scripts +ahoy drush php:script + +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 ``` -## Database and Content +### ❌ NEVER Do This + +```bash +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: -### Content Management +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); -### Solr Search +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations + +### Solr Search Service ```bash -# Check Solr status +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status -- **GitHub Actions** for CI/CD - -- **Container Registry** deployments for containerized environments +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging -### Common Issues +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` + +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/services_no_solr/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/services_no_solr/CLAUDE.md index fe612f3f6..254480843 100644 --- a/.vortex/installer/tests/Fixtures/install/services_no_solr/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/services_no_solr/CLAUDE.md @@ -1,317 +1,663 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod ``` -## Database and Content +## PHP Script Execution (IMPORTANT) -### Content Management +### ✅ Correct Way: Use PHP Scripts -- Use Configuration Management for structure (content types, fields, views) -- Use database imports for content in non-production environments -- Use migration modules for structured content imports in production +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name + +# List available scripts +ahoy drush php:script -## Services Integration +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 +``` -### Valkey (Redis-compatible caching) +### ❌ NEVER Do This ```bash -# Check cache status -ahoy drush cache:rebuild +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); + +foreach ($nodes as $node) { + print $node->getTitle(); +} ``` -### ClamAV Virus Scanning +## Service Integrations + +### Valkey/Redis Caching Service ```bash -# Test virus scanning functionality -ahoy drush clamav:scan +# Clear all caches (includes Valkey/Redis) +ahoy drush cache:rebuild -# Check ClamAV status -ahoy drush clamav:status +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -## Deployment +### ClamAV Virus Scanning Service -### CI/CD Pipeline -The project includes automated deployment via: +```bash +# Test virus scanning functionality +ahoy drush clamav:scan /path/to/test/file -- **GitHub Actions** for CI/CD +# Check ClamAV daemon status +ahoy drush clamav:status -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack ``` -### Dependency Management +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users +``` + +#### Test Data Conventions + +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked ``` -### Debugging +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" +``` + +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy + +# Get admin login URL +ahoy login -# View logs +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging + +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` -### Common Issues +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/services_no_valkey/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/services_no_valkey/CLAUDE.md index 7d92dd7bc..1e4aed206 100644 --- a/.vortex/installer/tests/Fixtures/install/services_no_valkey/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/services_no_valkey/CLAUDE.md @@ -1,320 +1,667 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/star_wars +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod +``` + +## PHP Script Execution (IMPORTANT) + +### ✅ Correct Way: Use PHP Scripts + +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name + +# List available scripts +ahoy drush php:script + +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 ``` -## Database and Content +### ❌ NEVER Do This + +```bash +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: -### Content Management +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); -### Solr Search +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations + +### Solr Search Service ```bash -# Check Solr status +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment - -### CI/CD Pipeline -The project includes automated deployment via: -- **GitHub Actions** for CI/CD - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Add theme build tools +### Theme Dependencies ```bash -cd web/themes/custom/star_wars && yarn install [package] +# Navigate to theme directory +cd web/themes/custom/[theme_name] + +# Add frontend dependencies +yarn add [package-name] + +# Example: Add Bootstrap +yarn add bootstrap + +# Install dev dependencies +yarn add --dev sass webpack +``` + +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users ``` -### Dependency Management +#### Test Data Conventions -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked +``` + +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" ``` -### Debugging +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy -# View logs +# Get admin login URL +ahoy login + +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging -### Common Issues +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` + +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/installer/tests/Fixtures/install/theme_absent/CLAUDE.md b/.vortex/installer/tests/Fixtures/install/theme_absent/CLAUDE.md index 51424e2e8..beb317a6f 100644 --- a/.vortex/installer/tests/Fixtures/install/theme_absent/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/install/theme_absent/CLAUDE.md @@ -1,308 +1,645 @@ # Vortex Drupal Project - Development Guide + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state -``` +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision -### Database operations +# Reset to clean state (removes local changes) +ahoy reset +``` ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management + +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) -### Exporting Configuration +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` -## Database and Content +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` -### Content Management +## Custom Code Development -- Use Configuration Management for structure (content types, fields, views) -- Use database imports for content in non-production environments -- Use migration modules for structured content imports in production +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` -## Services Integration +## PHP Script Execution (IMPORTANT) -### Solr Search +### ✅ Correct Way: Use PHP Scripts ```bash -# Check Solr status +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name + +# List available scripts +ahoy drush php:script + +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 +``` + +### ❌ NEVER Do This + +```bash +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` + +### Creating PHP Scripts + +Create scripts in `scripts/custom/` directory: + +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); + +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations + +### Solr Search Service + +```bash +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status -``` - -## Deployment -### CI/CD Pipeline -The project includes automated deployment via: - -- **GitHub Actions** for CI/CD - -- **Container Registry** deployments for containerized environments +# Update virus definitions +ahoy drush clamav:update +``` -## Common Tasks +## Dependency Management -### Adding Dependencies +### Adding Drupal Modules ```bash -# Add Drupal modules -ahoy composer require drupal/module_name +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -# Add development dependencies +# Add development-only modules ahoy composer require --dev drupal/devel + +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto ``` -### Adding JavaScript/CSS Libraries (npm packages) +### Adding JavaScript/CSS Libraries -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -1. Define the package in `composer.json` under the `repositories` section: +1. **Add to composer.json repositories section:** ```json { - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" } - ] + } + } + ] } ``` -2. Require the package using Composer: +1. **Install via Composer:** ```bash -ahoy composer require gdsmith/jquery.easing +ahoy composer require vendor/library-name ``` -### Dependency Management +## Testing Best Practices + +### Writing Behat Tests (BDD) + +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +#### Standard User Types + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users +``` + +#### Test Data Conventions + +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region +``` + +#### Discovering Available Step Definitions -To manually check for updates: ```bash -ahoy composer outdated +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked ``` -### Debugging +### Content Type Testing Process + +When creating comprehensive tests for content types: + +1. **Analyze Configuration First** + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +1. **Create Supporting Entities** + +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | +``` + +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" +``` + +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy + +# Get admin login URL +ahoy login -# View logs +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging + +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` -### Common Issues +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +- **GitHub Actions** - See `.github/workflows/` + +### Hosting Platforms + +- **Container Registry** - Docker-based deployments + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.* diff --git a/.vortex/tests/lint.markdown.sh b/.vortex/tests/lint.markdown.sh index d309f25fe..5de67e5ef 100755 --- a/.vortex/tests/lint.markdown.sh +++ b/.vortex/tests/lint.markdown.sh @@ -16,7 +16,9 @@ ROOT_DIR="$(dirname "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)")" "${ROOT_DIR}/.vortex/tests/node_modules/.bin/markdownlint-cli2" \ --config "${ROOT_DIR}/.vortex/tests/.markdownlint.yaml" \ "${ROOT_DIR}"/.vortex/README.md \ + "${ROOT_DIR}"/.vortex/CLAUDE.md \ "${ROOT_DIR}"/docs/*.md \ + "${ROOT_DIR}"/CLAUDE.md \ "${ROOT_DIR}"/README.md \ "${ROOT_DIR}"/README.dist.md \ "${ROOT_DIR}"/SECURITY.md \ diff --git a/CLAUDE.md b/CLAUDE.md index 2ac9001c5..6fd87698b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,389 +2,739 @@ [//]: # (#;< VORTEX_DEV) -> **🚀 PROJECT MODE**: This guide helps with **developing Drupal projects** created from the Vortex template. +> **🚀 PROJECT MODE**: This guide helps with **developing Drupal projects** +> created from the Vortex template. > -> For **maintaining the Vortex template itself**, see the maintenance guide: `.vortex/CLAUDE.md` +> For **maintaining the Vortex template itself**, see the maintenance guide: +`.vortex/CLAUDE.md` [//]: # (#;> VORTEX_DEV) + + ## Project Overview -This is a Drupal project built with **Vortex** - a comprehensive Drupal project template by DrevOps that provides production-ready development and deployment workflows. +This is a **production-ready Drupal project** built with **Vortex** - a +comprehensive Drupal project template by DrevOps that provides: + +- 🐳 **Docker-based development environment** +- 🔄 **Automated CI/CD deployment workflows** +- 🧪 **Comprehensive testing framework** (PHPUnit + Behat) +- ⚙️ **Configuration management** (exportable configs) +- 🚀 **Production hosting integration** -## Quick Start +## Quick Start Commands ```bash -# Build the site locally +# STEP 1: Build the site locally (first time setup) ahoy build -# Start development environment +# STEP 2: Start development environment ahoy up -# Access the site +# STEP 3: Get site information and URLs ahoy info + +# STEP 4: Get admin login link +ahoy login ``` -## Local Development Commands (Ahoy) +## Core Development Workflow -### Environment management +### 1. Environment Management ```bash -ahoy up # Start Docker containers -ahoy down # Stop Docker containers -ahoy restart # Restart containers -ahoy info # Show project information and URLs +# Start Docker containers (daily workflow) +ahoy up + +# Stop Docker containers (end of day) +ahoy down + +# Restart all containers (troubleshooting) +ahoy restart + +# Show project URLs, container status, database info +ahoy info ``` -### Site building and provisioning +### 2. Site Building & Database ```bash -ahoy build # Build site from scratch -ahoy provision # Provision site (install/import DB) -ahoy reset # Reset to clean state +# Complete site rebuild (nuclear option) +ahoy build + +# Re-provision site (install/import fresh DB) +ahoy provision + +# Reset to clean state (removes local changes) +ahoy reset ``` [//]: # (#;< !DB_DOWNLOAD_SOURCE_NONE) -### Database operations - ```bash -ahoy download-db # Download fresh database -ahoy export-db # Export current database -ahoy import-db # Import database from file +# Download fresh database from remote source +ahoy download-db + +# Export current local database +ahoy export-db + +# Import database from file +ahoy import-db [path/to/dump.sql] ``` [//]: # (#;> !DB_DOWNLOAD_SOURCE_NONE) -### Development tools +### 3. Daily Development Tasks ```bash -ahoy drush [command] # Run Drush commands -ahoy composer [command] # Run Composer commands -ahoy phpcs # Run code style checks -ahoy phpcbf # Fix code style issues +# Run Drush commands (Drupal CLI) +ahoy drush [command] +# Examples: +ahoy drush status +ahoy drush cr # Clear cache +ahoy drush uli # Get login link + +# Run Composer commands (PHP dependencies) +ahoy composer [command] +# Examples: +ahoy composer install +ahoy composer require drupal/admin_toolbar ``` -### Code Quality +## Code Quality & Testing + +### Linting (Code Standards) ```bash -ahoy lint # Run all linting checks -ahoy lint-fix # Fix automatically fixable issues +# Check code style issues (PHP, JS, CSS) +ahoy lint + +# Automatically fix code style issues +ahoy lint-fix ``` -### Testing +### Testing Framework ```bash -ahoy test-unit # Run PHPUnit tests -ahoy test-bdd # Run Behat (BDD) tests -ahoy test # Run all tests -``` +# Run PHPUnit tests (unit/integration tests) +ahoy test-unit -#### Behat Feature Writing Standards +# Run Behat tests (behavioral/BDD tests) +ahoy test-bdd -When creating or updating Behat feature files, follow these conventions: +# Run ALL tests (unit + BDD) +ahoy test -- **User Story Format**: All features must use the standard user story format: - ```gherkin - As a [user type] - I want to [action] - So that [benefit] - ``` - -- **User Types**: Use consistent user types across features: - - `site visitor` - for anonymous users and general site access - - `site administrator` - for users with administrative privileges - - `content editor` - for users managing content - -- **No Punctuation**: Do not use commas or periods in user story statements - -- **Example**: - ```gherkin - Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - ``` - -## Project Structure - -``` -├── config/ # Drupal configuration (exported) -│ ├── default/ # Default configuration -│ ├── dev/ # Development-specific config -│ ├── stage/ # Staging-specific config -│ └── ci/ # CI-specific config -├── scripts/ -│ ├── vortex/ # Core Vortex deployment scripts -│ └── custom/ # Project-specific custom scripts -├── web/ # Drupal webroot -│ ├── modules/custom/ # Custom modules -│ ├── themes/custom/ # Custom themes -│ └── sites/default/ # Drupal site configuration -├── tests/ -│ ├── behat/ # Behavioral tests (BDD) -│ └── phpunit/ # Unit/integration tests -├── docker-compose.yml # Local development environment -└── .env # Environment configuration +# Run specific Behat feature +ahoy test-bdd tests/behat/features/homepage.feature ``` -## Configuration Management +## Configuration Management (Critical for Drupal) + +### Understanding Config Management -### Exporting Configuration +- **Structure changes** (content types, fields, views) = Configuration (exported + to code) +- **Content data** (nodes, users, media) = Database (not exported) + +### Export Configuration (After making admin changes) ```bash -# Export all configuration changes +# Export ALL configuration changes to code ahoy drush config:export +# Short version: +ahoy drush cex -# Export specific configuration +# Export with diff preview ahoy drush config:export --diff ``` -### Importing Configuration +### Import Configuration (Deploy config changes) ```bash -# Import configuration (usually part of deployment) +# Import configuration from code ahoy drush config:import +# Short version: +ahoy drush cim -# Import with specific source +# Import from specific environment ahoy drush config:import --source=../config/stage ``` +### Typical Config Workflow + +1. Make changes in Drupal admin UI +2. Run `ahoy drush cex` to export to code +3. Commit the config files to git +4. Deploy code and run `ahoy drush cim` on target environment + +## Project Structure (Critical Understanding) + +```text +your-project/ +├── .ahoy.yml # Ahoy task definitions +├── .env # Environment variables (local) +├── docker-compose.yml # Local development containers +├── composer.json # PHP dependencies +│ +├── config/ # Drupal configuration (version controlled) +│ ├── default/ # Base configuration (all environments) +│ ├── dev/ # Development-specific overrides +│ ├── stage/ # Staging-specific overrides +│ └── ci/ # CI-specific overrides +│ +├── web/ # Drupal webroot (document root) +│ ├── modules/custom/ # Your custom modules +│ ├── themes/custom/ # Your custom themes +│ ├── sites/default/ # Drupal site settings +│ └── index.php # Drupal entry point +│ +├── tests/ +│ ├── behat/ # Behavioral tests (user scenarios) +│ │ ├── features/ # Test scenarios (.feature files) +│ │ └── behat.yml # Behat configuration +│ └── phpunit/ # Unit/integration tests +│ +└── scripts/ + ├── vortex/ # Core Vortex scripts (don't modify) + └── custom/ # Project-specific scripts +``` + +## Custom Code Development + +### Creating Custom Modules + +```bash +# Generate custom module scaffold +ahoy drush generate:module + +# Location: web/modules/custom/[module_name]/ +# Enable module: +ahoy drush pm:install [module_name] +``` + [//]: # (#;< DRUPAL_THEME) ### Theme Development ```bash # Navigate to custom theme -cd web/themes/custom/your_site_theme +cd web/themes/custom/[theme_name] # Install theme dependencies yarn install -# Build theme assets +# Build theme assets (CSS/JS) yarn run build # Watch for changes during development yarn run watch + +# Build for production +yarn run build:prod ``` [//]: # (#;> DRUPAL_THEME) -## Database and Content +## PHP Script Execution (IMPORTANT) -[//]: # (#;< !DB_DOWNLOAD_SOURCE_NONE) +### ✅ Correct Way: Use PHP Scripts + +```bash +# Run PHP script with full Drupal bootstrap +ahoy drush php:script script_name + +# List available scripts +ahoy drush php:script + +# Run with custom script path +ahoy drush php:script script_name --script-path=scripts/custom + +# Pass arguments to script (note the -- separator) +ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 +``` + +### ❌ NEVER Do This + +```bash +# DANGEROUS - Never evaluate PHP directly! +ahoy drush php:eval "dangerous_code_here" +``` -### Content Management +### Creating PHP Scripts -- Use Configuration Management for structure (content types, fields, views) -- Use database imports for content in non-production environments -- Use migration modules for structured content imports in production +Create scripts in `scripts/custom/` directory: -## Services Integration +```php +getStorage('node') + ->loadByProperties(['type' => 'page']); + +foreach ($nodes as $node) { + print $node->getTitle(); +} +``` + +## Service Integrations [//]: # (#;< SERVICE_SOLR) -### Solr Search +### Solr Search Service ```bash -# Check Solr status +# Check Solr search status ahoy drush search-api:status -# Index content +# Index all content to Solr ahoy drush search-api:index -# Clear Solr index +# Clear and rebuild Solr index ahoy drush search-api:clear +ahoy drush search-api:index + +# Check Solr server connection +ahoy drush search-api:server-status ``` [//]: # (#;> SERVICE_SOLR) [//]: # (#;< SERVICE_VALKEY) -### Valkey (Redis-compatible caching) +### Valkey/Redis Caching Service ```bash -# Check cache status +# Clear all caches (includes Valkey/Redis) ahoy drush cache:rebuild -# Clear Redis/Valkey cache -ahoy drush php-eval "\Drupal\redis\Client\ClientInterface::flushAll();" +# Check Redis/Valkey connection status +ahoy drush php:script -- redis_status + +# Flush Redis cache specifically +ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" ``` [//]: # (#;> SERVICE_VALKEY) [//]: # (#;< SERVICE_CLAMAV) -### ClamAV Virus Scanning +### ClamAV Virus Scanning Service ```bash # Test virus scanning functionality -ahoy drush clamav:scan +ahoy drush clamav:scan /path/to/test/file -# Check ClamAV status +# Check ClamAV daemon status ahoy drush clamav:status + +# Update virus definitions +ahoy drush clamav:update ``` [//]: # (#;> SERVICE_CLAMAV) -## Deployment +## Dependency Management -### CI/CD Pipeline -The project includes automated deployment via: +### Adding Drupal Modules -[//]: # (#;< CI_PROVIDER_GHA) +```bash +# Add contributed modules +ahoy composer require drupal/admin_toolbar +ahoy composer require drupal/pathauto -- **GitHub Actions** for CI/CD +# Add development-only modules +ahoy composer require --dev drupal/devel -[//]: # (#;> CI_PROVIDER_GHA) +# Enable installed modules +ahoy drush pm:install admin_toolbar pathauto +``` -[//]: # (#;< CI_PROVIDER_CIRCLECI) +### Adding JavaScript/CSS Libraries -- **CircleCI** for CI/CD +For npm packages that need to be Drupal libraries, define them as inline +Composer packages: -[//]: # (#;> CI_PROVIDER_CIRCLECI) +1. **Add to composer.json repositories section:** -[//]: # (#;< HOSTING_LAGOON) +```json +{ + "repositories": [ + { + "type": "package", + "package": { + "name": "vendor/library-name", + "type": "drupal-library", + "version": "1.0.0", + "source": { + "type": "git", + "url": "https://github.com/vendor/library-name", + "reference": "1.0.0" + } + } + } + ] +} +``` -- **Lagoon** for hosting +1. **Install via Composer:** -[//]: # (#;> HOSTING_LAGOON) +```bash +ahoy composer require vendor/library-name +``` -[//]: # (#;< HOSTING_ACQUIA) +[//]: # (#;< DRUPAL_THEME) -- **Acquia** for hosting +### Theme Dependencies -[//]: # (#;> HOSTING_ACQUIA) +```bash +# Navigate to theme directory +cd web/themes/custom/[theme_name] -[//]: # (#;< DEPLOY_TYPE_CONTAINER_REGISTRY) +# Add frontend dependencies +yarn add [package-name] -- **Container Registry** deployments for containerized environments +# Example: Add Bootstrap +yarn add bootstrap -[//]: # (#;> DEPLOY_TYPE_CONTAINER_REGISTRY) +# Install dev dependencies +yarn add --dev sass webpack +``` -## Common Tasks +[//]: # (#;> DRUPAL_THEME) -### Adding Dependencies +## Testing Best Practices -```bash -# Add Drupal modules -ahoy composer require drupal/module_name +### Writing Behat Tests (BDD) -# Add development dependencies -ahoy composer require --dev drupal/devel +#### User Story Format (Required) + +All Behat features MUST follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] ``` -### Adding JavaScript/CSS Libraries (npm packages) +#### Standard User Types -To install JavaScript or CSS libraries as Drupal libraries with Composer, -they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users +``` -1. Define the package in `composer.json` under the `repositories` section: +#### Test Data Conventions -```json -{ - "repositories": [ - { - "type": "package", - "package": { - "name": "gdsmith/jquery.easing", - "type": "drupal-library", - "version": "1.4.1", - "source": { - "type": "git", - "url": "https://github.com/gdsmith/jquery.easing", - "reference": "1.4.1" - } - } - } - ] -} +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +#### Example Feature File + +```gherbal +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see the "main navigation" region + And I should see "About Us" in the "navigation" region ``` -2. Require the package using Composer: +#### Discovering Available Step Definitions ```bash -ahoy composer require gdsmith/jquery.easing +# Generate step definitions reference (run once) +ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt + +# Use the cached file for reference, don't regenerate unless asked ``` -[//]: # (#;< DRUPAL_THEME) +### Content Type Testing Process -### Add theme build tools +When creating comprehensive tests for content types: -```bash -cd web/themes/custom/your_site_theme && yarn install [package] -``` +1. **Analyze Configuration First** -[//]: # (#;> DRUPAL_THEME) + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields -### Dependency Management +1. **Create Supporting Entities** -Dependencies are automatically updated via RenovateBot: -- **Composer dependencies**: Updated automatically with compatibility checks -- **Node.js dependencies**: Updated in theme directories -- **Docker images**: Base image updates for containers +```gherkin +Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | -To manually check for updates: -```bash -ahoy composer outdated + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | ``` -### Debugging +1. **Test All Visible Fields** + +```gherkin +Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" +``` + +## Debugging & Troubleshooting + +### Development Tools ```bash # Enable development modules -ahoy drush pm:install devel webprofiler +ahoy drush pm:install devel webprofiler stage_file_proxy + +# Get admin login URL +ahoy login -# View logs +# View recent log entries ahoy drush watchdog:show -# Clear caches +# Clear all caches ahoy drush cache:rebuild + +# Check system status +ahoy drush status ``` -### Performance +### Performance Optimization ```bash -# Enable caching +# Enable CSS/JS aggregation ahoy drush config:set system.performance css.preprocess 1 ahoy drush config:set system.performance js.preprocess 1 -# Clear specific caches +# Clear render cache ahoy drush cache:rebuild-external + +# Check database updates needed +ahoy drush updatedb:status ``` -## Troubleshooting +### Container Debugging -### Common Issues +```bash +# Check container status +docker-compose ps + +# View container logs +docker-compose logs [service_name] +# Examples: +docker-compose logs web +docker-compose logs db + +# Access container shell +docker-compose exec web bash +docker-compose exec db mysql -u drupal -p drupal +``` + +### Common Issues & Solutions + +**Site not loading:** -**Site not loading locally:** ```bash ahoy down && ahoy up -ahoy info # Check URLs and container status +ahoy info # Verify URLs and ports ``` -**Database connection issues:** +**Database connection errors:** + ```bash -# Check database container -docker-compose ps -ahoy reset # Rebuild if needed +docker-compose ps # Check if database container is running +ahoy reset # Nuclear option: rebuild everything +``` + +**Permission issues:** + +```bash +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +**Memory issues during composer install:** + +```bash +# Increase PHP memory temporarily +ahoy composer install --no-dev --optimize-autoloader +``` + +## CI/CD & Deployment + +### Automated Deployment + +This project includes automated deployment via: + +[//]: # (#;< CI_PROVIDER_GHA) + +- **GitHub Actions** - See `.github/workflows/` + +[//]: # (#;> CI_PROVIDER_GHA) + +[//]: # (#;< CI_PROVIDER_CIRCLECI) + +- **CircleCI** - See `.circleci/config.yml` + +[//]: # (#;> CI_PROVIDER_CIRCLECI) + +### Hosting Platforms + +[//]: # (#;< HOSTING_LAGOON) + +- **Lagoon** - Container-based hosting platform + +[//]: # (#;> HOSTING_LAGOON) + +[//]: # (#;< HOSTING_ACQUIA) + +- **Acquia Cloud** - Enterprise Drupal hosting + +[//]: # (#;> HOSTING_ACQUIA) + +[//]: # (#;< DEPLOY_TYPE_CONTAINER_REGISTRY) + +- **Container Registry** - Docker-based deployments + +[//]: # (#;> DEPLOY_TYPE_CONTAINER_REGISTRY) + +### Manual Deployment Commands + +```bash +# Export configuration before deployment +ahoy drush config:export + +# Run database updates +ahoy drush updatedb + +# Import configuration +ahoy drush config:import + +# Clear caches +ahoy drush cache:rebuild + +# Full deployment sequence +ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild +``` + +## Getting Help & Resources + +### Command Help + +```bash +# List all available ahoy commands +ahoy --help + +# Get help for specific command +ahoy [command] --help + +# Examples: +ahoy build --help +ahoy test-bdd --help +``` + +### Log Files & Debugging + +```bash +# View ahoy logs +ahoy logs + +# Check container logs +docker-compose logs --tail=50 web + +# View Drupal watchdog logs +ahoy drush watchdog:show --count=20 ``` -## Resources +### Documentation Resources - **Vortex Documentation**: https://www.vortextemplate.com - **Drupal Documentation**: https://www.drupal.org/docs - **Drush Documentation**: https://www.drush.org - **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy +- **Docker Compose**: https://docs.docker.com/compose/ -## Getting Help +### Project-Specific Help -- Check `ahoy --help` for available commands -- Use `ahoy [command] --help` for specific command help -- Review project-specific documentation in `/docs` (if available) -- Check environment logs: `ahoy logs` +- Check `/docs` directory for additional project documentation +- Review `README.md` in project root +- Check `.ahoy.yml` for custom commands +- Review `composer.json` for installed packages and scripts --- -*This guide covers the essentials for working with your Vortex-powered Drupal project. As your project grows, consider expanding this guide with project-specific workflows and conventions.* + + +*This guide covers the complete development workflow for your Vortex-powered +Drupal project. Keep this guide updated as your project grows and add +project-specific conventions below.*