[#2096] Updated to use cweagans/composer-patches v2.

Author: AlexSkrypnyk

.vortex/CLAUDE.md

@@ -330,13 +330,32 @@ The installer uses a **baseline + diff** system for managing test fixtures:
 
 ### Updating Fixtures
 
-**Critical**: Use the proper fixture update mechanism:
+**CRITICAL - Use the Unified Ahoy Command**:
+
+The correct way to update fixtures is to use the unified `ahoy update-fixtures` command from the `.vortex` directory:
 
 ```bash
-cd .vortex/installer
+cd .vortex
 
-# Update all fixtures
-UPDATE_FIXTURES=1 composer test
+# This is the CORRECT way to update all fixtures
+ahoy update-fixtures
+```
+
+**What this command does**:
+- Updates template test fixtures in `tests/` directory
+- Updates installer test fixtures in `installer/` directory
+- Handles baseline fixtures first
+- Updates all scenario-specific fixtures
+- Runs tests twice to properly handle fixture updates (first run may fail, second should pass)
+
+**DO NOT manually run `UPDATE_FIXTURES=1` commands** - the `ahoy update-fixtures` command handles everything automatically.
+
+### Alternative: Manual Fixture Updates (Advanced)
+
+For specific fixture updates or debugging, you can use manual commands:
+
+```bash
+cd .vortex/installer
 
 # Update specific test fixtures
 UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter "testInstall.*baseline"
@@ -352,9 +371,10 @@ UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter 'testInstall.*"services.*no.*cla
 
 ### 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
+1. **Use ahoy update-fixtures**: This is the standard and recommended approach
+2. **Alternative - Baseline First**: Update baseline fixtures manually if needed
+3. **Alternative - Scenario Diffs**: Run individual scenario tests to update specific diffs
+4. **Validation**: Verify tests pass without UPDATE_FIXTURES flag
 
 ## Script Output Formatters
 
@@ -397,7 +417,7 @@ info "Finished executing example operations in non-production environment."
 
 1. **Update Main Script**: Modify the script in the template (outside .vortex/)
 2. **Update BATS Tests**: Update test assertions in `.vortex/tests/bats/`
-3. **Update Installer Fixtures**: Use `UPDATE_FIXTURES=1` process
+3. **Update Installer Fixtures**: Run `ahoy update-fixtures` from `.vortex/` directory
 
 ### Provision Script BATS Test Logic
 
@@ -712,12 +732,13 @@ Each system:
 
 ### 2. Installer System (.vortex/installer/)
 
-**Fixture Updates Can Be Finicky**:
+**Fixture Updates**:
 
-- The `UPDATE_FIXTURES=1` mechanism can have defects
-- Try updating baseline first, then individual scenarios
-- Use filtered test runs for specific scenarios
+- **Use `ahoy update-fixtures`** from `.vortex/` directory - this is the standard approach
+- The unified command updates all fixtures automatically
+- Runs tests twice to handle fixture updates properly (first run may fail, second should pass)
 - Be patient - full test suite can take several minutes
+- For debugging specific scenarios, manual `UPDATE_FIXTURES=1` commands can be used
 
 **Handler Development**:
 
@@ -771,10 +792,13 @@ yarn test --updateSnapshot     # Update component snapshots
 **Fixture Update Issues**:
 
 ```bash
-# Try baseline first
-UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter "testInstall.*baseline"
+# RECOMMENDED: Use the unified command
+cd .vortex
+ahoy update-fixtures
 
-# Then individual scenarios
+# ALTERNATIVE: Manual updates for specific scenarios
+cd .vortex/installer
+UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter "testInstall.*baseline"
 UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter 'testInstall.*"scenario_name"'
 
 # Check for test timeouts - increase if needed
@@ -1209,7 +1233,9 @@ $this->cmd('ahoy export-db', '! Containers are not running.', arg: $args);
 **Installer System** (`.vortex/installer/`):
 
 - **CRITICAL**: NEVER directly modify files under `.vortex/installer/tests/Fixtures/`
-- These are test fixtures that must be updated via `UPDATE_FIXTURES=1` mechanism
+- These are test fixtures that must be updated via `ahoy update-fixtures` command from `.vortex/` directory
+- The unified `ahoy update-fixtures` command handles all fixture updates automatically
+- For debugging, manual `UPDATE_FIXTURES=1` commands can be used from `.vortex/installer/`
 - Always test with baseline scenario first, then individual scenarios
 - Preserve handler execution order and batching patterns
 

.vortex/docs/content/drupal/composer.mdx

@@ -79,18 +79,10 @@ The [`repositories`](https://getcomposer.org/doc/04-schema.md#repositories)
 section defines custom package repositories, essential for accessing packages
 outside the default Packagist repository.
 
-See [Working with packages](../workflows/development#working-with-composer-packages) for more information on
-how to provide custom and override existing packages in your project.
-
 - [`drupal`](https://www.drupal.org/docs/develop/using-composer/using-packagesdrupalorg):
   Serves as the official source for Drupal modules, themes, and distributions.
   It's crucial for a Drupal project using Composer, as it allows access to
   Drupal-specific packages not available on Packagist.
-- [`asset-packagist`](https://asset-packagist.org/): Enables the installation of
-  Bower and NodeJs packages via Composer. This is especially important for Drupal
-  projects needing front-end libraries and tools, bridging the gap between
-  Composer's PHP-centric ecosystem and the broader world of front-end package
-  management.
 
 ### `require`
 
@@ -104,9 +96,11 @@ specifies the essential packages and libraries your project needs.
   install packages to the correct location based on the specified package type
   such as `drupal-module`, `drupal-theme`, `drupal-profile`, etc.
 - [`cweagans/composer-patches`](https://github.com/cweagans/composer-patches):
-  Allows applying patches to Composer packages, useful for incorporating fixes
-  not yet in official releases.
-  See [Working with packages](../workflows/development#patching) for more
+  Enables git-based patching of Composer packages, useful for incorporating fixes
+  not yet in official releases. Version 2.x uses `git apply` for cross-platform
+  consistency and generates a `patches.lock.json` file to ensure reproducible
+  builds with SHA-256 checksums.
+  See [Patching](../workflows/development#patching) for more
   information on how to work with patches.
 - `drupal/admin_toolbar`, `drupal/clamav`, `drupal/coffee`, etc. - Drupal
   modules that provide various site administration and development helping
@@ -266,9 +260,11 @@ a source of custom configuration for various packages. These packages read
 settings from this section to tailor their behavior according to the specific
 needs and structure of your Drupal project.
 
-- [`composer-exit-on-patch-failure`](https://github.com/cweagans/composer-patches):
-  This setting, when enabled, causes Composer to exit if a patch from
-  the `cweagans/composer-patches` plugin fails to apply.
+- **patches.lock.json**: Automatically generated by `cweagans/composer-patches`
+  v2.x. This file contains patch metadata and SHA-256 checksums, and must be
+  committed to version control (like `composer.lock`). It ensures reproducible
+  builds across teams and CI/CD environments by verifying patch integrity and
+  making the patch state explicit and trackable.
 - [`drupal-scaffold`](https://www.drupal.org/docs/develop/using-composer/using-drupals-composer-scaffold):
   This setting controls which files should be scaffolded:
   - `locations`: Specifies the location of the web root (the directory

.vortex/docs/content/workflows/development.mdx

@@ -217,19 +217,93 @@ To override package installation paths, modify `composer.json`:
 
 ### Patching
 
-If you need to apply patches to included dependencies, use the `composer-patches` plugin. Add the patch definition in `composer.json` under the `extra.patches` section:
+Vortex uses [`cweagans/composer-patches`](https://github.com/cweagans/composer-patches) v2.x for applying patches to Composer dependencies. Version 2.x uses git-based patching with `git apply` for better cross-platform consistency.
 
-```json
-"extra": {
-    "patches": {
-        "drupal/foobar": {
-            "Patch description": "URL or local path to patch"
+:::tip
+
+For official documentation, visit: [Composer Patches Recommended Workflows](https://docs.cweagans.net/composer-patches/usage/recommended-workflows/)
+
+:::
+
+#### Understanding `patches.lock.json`
+
+Composer Patches v2.x automatically generates a `patches.lock.json` file that contains:
+
+- Patch metadata (URLs, descriptions, target packages)
+- SHA-256 checksums for patch verification
+
+**This file must be committed to version control** (like `composer.lock`).
+
+**Benefits:**
+
+- Ensures reproducible builds across teams and CI/CD environments
+- Verifies patch integrity with checksums
+- Prevents "works on my machine" issues with patches
+- Makes the patch state explicit and trackable
+
+#### Adding a New Patch
+
+1. Define the patch in `composer.json` under `extra.patches`:
+
+    ```json
+    "extra": {
+        "patches": {
+            "drupal/foobar": {
+                "Fix for issue #123": "https://www.drupal.org/files/issues/fix-123.patch"
+            }
         }
     }
-}
-```
+    ```
+
+2. Regenerate `patches.lock.json`:
+
+    ```bash
+    composer patches-relock
+    ```
+
+3. Remove and reinstall patched packages:
+
+    ```bash
+    composer patches-repatch
+    ```
+
+    :::warning
+    `composer patches-repatch` removes patched dependencies from `vendor/` and reinstalls them. Ensure you have no unsaved changes in those directories.
+    :::
+
+4. Update `composer.lock`:
+
+    ```bash
+    composer update --lock
+    ```
+
+#### Removing a Patch
+
+1. Delete the patch definition from `composer.json`
+
+2. Regenerate `patches.lock.json`:
+
+    ```bash
+    composer patches-relock
+    ```
+
+3. Manually delete the affected dependency:
+
+    ```bash
+    rm -rf vendor/drupal/foobar
+    ```
+
+4. Reinstall without the patch:
+
+    ```bash
+    composer patches-repatch
+    ```
+
+5. Update `composer.lock`:
 
-Run `composer update drupal/foobar` after adding patches to apply them.
+    ```bash
+    composer update --lock
+    ```
 
 ## Resetting the codebase
 

.vortex/docs/cspell.json

@@ -28,6 +28,7 @@
         "ddev",
         "dealerdirect",
         "drevops",
+        "drupalcode",
         "drush",
         "ergebnis",
         "gherkinlint",

.vortex/installer/composer.json

@@ -21,7 +21,7 @@
         "alexskrypnyk/file": "^0.13",
         "alexskrypnyk/str2name": "^1.4",
         "composer/composer": "^2.8",
-        "cweagans/composer-patches": "^1.7",
+        "cweagans/composer-patches": "^2.0",
         "czproject/git-php": "^4.3",
         "laravel/prompts": "^0.3.7",
         "nikic/iter": "^2.4",
@@ -77,9 +77,6 @@
         },
         "sort-packages": true
     },
-    "extra": {
-        "composer-exit-on-patch-failure": true
-    },
     "scripts": {
         "build": [
             "@composer bin box require --dev humbug/box",

.vortex/installer/tests/Fixtures/install/_baseline/composer.json

@@ -91,7 +91,6 @@
         "sort-packages": true
     },
     "extra": {
-        "composer-exit-on-patch-failure": true,
         "drupal-scaffold": {
             "file-mapping": {
                 "[project-root]/.editorconfig": false,

.vortex/installer/tests/Fixtures/install/ai_instructions_claude/CLAUDE.md

@@ -351,10 +351,37 @@ ahoy drush pm:install admin_toolbar pathauto
 
 When contributed modules need fixes or customizations, use the proper patching workflow with `cweagans/composer-patches`.
 
+Vortex uses **composer-patches v2.x** which provides git-based patching with improved reliability and reproducibility.
+
+#### Key Features of v2
+
+- **Git-based patching**: Uses `git apply` exclusively for cross-platform consistency
+- **patches.lock.json**: Automatically generated file with patch metadata and SHA-256 checksums
+- **New commands**:
+  - `composer patches-relock` - Regenerate patches.lock.json after adding/removing patches
+  - `composer patches-repatch` - Remove and reinstall patched dependencies
+- **Automatic failure on patch errors**: Patches must apply successfully or installation fails
+
+#### Understanding patches.lock.json
+
+This file is automatically generated and **must be committed to version control** (like composer.lock).
+
+**What it contains:**
+- Patch metadata (URLs, descriptions, target packages)
+- SHA-256 checksums for patch verification
+
+**Why it matters:**
+- Ensures reproducible builds across teams and CI/CD
+- Verifies patch integrity with checksums
+- Prevents "works on my machine" issues
+- Makes patch state explicit and trackable
+
+**Always commit this file** after adding or removing patches.
+
 #### Prerequisites for Patching
 
-- Project uses `cweagans/composer-patches` package
-- Git is available for version control
+- Project uses `cweagans/composer-patches` package (v2.x)
+- Git is available for version control (required by v2)
 - Access to Drupal.org git repositories
 
 #### Patch Storage and Configuration
@@ -469,14 +496,26 @@ git diff
 
 Step 7: Integrate into Project
 
-Add the patch to your project's composer configuration and test:
+Add the patch to your project's composer configuration and apply it using v2 commands:
 
 ```bash
-# Update the specific module to apply patch
-ahoy composer require drupal/module_name
+# Add patch definition to composer.json extra.patches section
+
+# Regenerate patches.lock.json
+ahoy composer patches-relock
+
+# Remove and reinstall patched package
+ahoy composer patches-repatch
+
+# Update composer.lock
+ahoy composer update --lock
 
 # Verify no patch application errors
 # Check that functionality works as expected
+
+# Commit all changes
+git add composer.json composer.lock patches.lock.json patches/
+git commit -m "Added patch for drupal/module_name."
 ```
 
 Step 8: Clean Up