Release v2.0.30: PHP 8.1+, opt-in wrapper updates, and release docs

Document breaking PHP requirement and wrapper overwrite policy, align tests
with opt-in auto_update_wrapper behavior, and finalize changelog/upgrading
for the v2.0.30 tag.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HecFranco

README.md

@@ -50,7 +50,19 @@ After installation, two files will be copied to your project root:
 
 **Note:** These files should be committed to your repository so they're available to all team members. The plugin will remove any old `.ignore.txt` entries from `.gitignore` if they exist.
 
-**Auto-update:** The `generate-composer-require.sh` script is automatically updated when you run `composer update` if the content differs from the version in vendor. This ensures you always have the latest version of the script.
+**Wrapper updates:** On first install, `generate-composer-require.sh` is copied to your project root. On later `composer update` runs, the plugin **does not overwrite** a local wrapper that differs from the package copy unless you opt in:
+
+```json
+{
+  "extra": {
+    "composer-update-helper": {
+      "auto_update_wrapper": true
+    }
+  }
+}
+```
+
+When opt-in is disabled (default), Composer shows a comment with MD5 hashes if the wrapper differs. See [Configuration](docs/CONFIGURATION.md#composer-plugin-options).
 
 ### Architecture
 

docs/CHANGELOG.md

@@ -7,10 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.30] - 2026-07-09
+
+### Breaking Changes
+
+- **PHP requirement**: Minimum PHP version is now `>=8.1 <8.6` (previously `>=7.4`). Projects on PHP 7.4 or 8.0 must upgrade PHP before updating this package.
+
+### Added
+
+- **Opt-in wrapper auto-update**: New `extra.composer-update-helper.auto_update_wrapper` flag in the consuming project's `composer.json` to overwrite a customized `generate-composer-require.sh` when the package copy differs (disabled by default to protect local changes).
+- **Static analysis and refactoring toolchain**: PHPStan and Rector added to `require-dev`, with `composer phpstan`, `composer rector`, and `composer rector-dry` scripts.
+- **Pre-release pipeline**: `make release-check` runs composer sync, code style, Rector dry-run, PHPStan, and coverage validation.
+- **Documentation**: [INSTALLATION.md](INSTALLATION.md), [SECURITY.md](SECURITY.md), [SPEC-DRIVEN-DEVELOPMENT.md](SPEC-DRIVEN-DEVELOPMENT.md), and [SPEC-KIT.md](SPEC-KIT.md).
+- **CI/CD integrations**: CodeRabbit workflow, PR lint, stale issue management, Scrutinizer configuration, and expanded GitHub Actions CI matrix.
+- **Spec Kit / Specify**: Project scaffolding for spec-driven development (`.specify/`, baseline spec `specs/001-baseline/`).
+- **Composer archive exclusions**: `demo/` and `.cursor/` excluded from distribution archives.
+
+### Changed
+
+- **Plugin wrapper install behavior**: The plugin installs the wrapper on first run; subsequent updates only overwrite when `auto_update_wrapper` is `true` or content already matches. When skipped, a comment explains how to enable overwrite.
+- **Test layout**: PHPUnit tests reorganized into `tests/Unit/` and `tests/Integration/`.
+- **README**: Packagist badges, documentation index, PHP 8.1+ requirement, and wrapper update policy.
+- **Plugin and Installer**: Code quality pass (PHPStan/Rector/PHP-CS-Fixer), modern string checks (`str_starts_with`), and clearer PHPDoc.
+- **composer.json**: Corrected GitHub homepage/support URLs; Symfony FrameworkBundle added as dev dependency for static analysis.
+
 ### Documentation
 
 - **README** — Architecture: updated approximate line counts for `generate-composer-require.sh` and `process-updates.php` (and noted they can change between releases). Language list in the YAML example points to **CONFIGURATION.md** for the full locale set instead of a partial inline list.
-- **Plugin.php** — `installFiles()` docblock now matches behavior (script is updated when vendor copy differs), not “first install only”.
+- **Plugin.php** — `installFiles()` docblock documents first-install copy and opt-in overwrite behavior.
+- **CONFIGURATION.md** — Documents `extra.composer-update-helper.auto_update_wrapper`.
+
+> **Note**: See [UPGRADING.md](UPGRADING.md#upgrading-to-2030-2026-07-09) for migration notes.
 
 ## [2.0.29] - 2026-01-22
 

docs/CONFIGURATION.md

@@ -2,6 +2,31 @@
 
 This guide covers all configuration options for Composer Update Helper.
 
+## Composer plugin options
+
+These settings live in the **consuming project's** `composer.json` under `extra.composer-update-helper` (not in `generate-composer-require.yaml`).
+
+### `auto_update_wrapper`
+
+Controls whether `composer install` / `composer update` may overwrite an existing `generate-composer-require.sh` when it differs from the package copy.
+
+| Value | Behavior |
+|-------|----------|
+| `false` (default) | Keep the local wrapper; show a comment with MD5 hashes when versions differ |
+| `true` | Overwrite the local wrapper with the package version |
+
+```json
+{
+  "extra": {
+    "composer-update-helper": {
+      "auto_update_wrapper": true
+    }
+  }
+}
+```
+
+Use `true` when you want the wrapper to track package updates automatically. Leave the default when you maintain local customizations to the shell script.
+
 ## Package Configuration
 
 The script searches for configuration files in the current directory (where `composer.json` is located). It supports both `.yaml` and `.yml` extensions, with `.yaml` taking priority.

docs/UPGRADING.md

@@ -18,6 +18,44 @@ This guide will help you upgrade Composer Update Helper to newer versions.
 
 ## Version-Specific Upgrade Notes
 
+### Upgrading to 2.0.30+ (2026-07-09)
+
+#### Breaking Changes
+
+- **PHP `>=8.1 <8.6` required**: Upgrade your runtime before updating the package. PHP 7.4 and 8.0 are no longer supported.
+
+#### What's Changed
+
+- **Wrapper auto-update is opt-in**: The plugin no longer silently overwrites a customized `generate-composer-require.sh` on `composer update`. By default, if your local wrapper differs from the package copy, Composer prints a comment with MD5 hashes and keeps your file.
+
+  To allow automatic overwrite again, add to your project's `composer.json`:
+
+  ```json
+  {
+    "extra": {
+      "composer-update-helper": {
+        "auto_update_wrapper": true
+      }
+    }
+  }
+  ```
+
+- **Development tooling**: Maintainers and contributors can run `make release-check` (PHP-CS-Fixer, Rector dry-run, PHPStan, PHPUnit with coverage).
+
+#### Migration Steps
+
+1. Confirm PHP `>=8.1` on your machine and CI.
+2. Update the package: `composer update nowo-tech/composer-update-helper`.
+3. If you customized `generate-composer-require.sh`, decide whether to keep your version or enable `auto_update_wrapper`.
+4. Review new docs: [INSTALLATION.md](INSTALLATION.md), [SECURITY.md](SECURITY.md).
+
+#### Breaking Changes Summary
+
+| Change | Action |
+|--------|--------|
+| PHP >=8.1 required | Upgrade PHP before updating the package |
+| Wrapper overwrite opt-in | Set `auto_update_wrapper: true` if you want silent updates |
+
 ### Upgrading to 2.0.29+ (2026-01-22)
 
 #### What's Changed

src/Plugin.php

@@ -13,6 +13,7 @@
 
 use function count;
 use function dirname;
+use function is_array;
 use function sprintf;
 
 /**
@@ -619,7 +620,7 @@ private function removeFiles(IOInterface $io): void
      */
     private function readProjectComposerJson(): array
     {
-        $vendorDir = $this->composer->getConfig()->get('vendor-dir');
+        $vendorDir        = $this->composer->getConfig()->get('vendor-dir');
         $composerJsonPath = dirname((string) $vendorDir) . '/composer.json';
 
         if (!file_exists($composerJsonPath)) {

tests/Unit/PluginTest.php

@@ -15,6 +15,8 @@
 
 use function dirname;
 
+use const JSON_THROW_ON_ERROR;
+
 /**
  * Test suite for the Plugin class.
  * Tests the Composer plugin functionality including file installation,
@@ -213,7 +215,7 @@ public function testOnPostUpdateUpdatesGitignore(): void
         @rmdir($tempDir);
     }
 
-    public function testInstallFilesSkipsWhenFileExists(): void
+    public function testInstallFilesSkipsWhenFileExistsWithoutAutoUpdateOptIn(): void
     {
         $tempDir    = sys_get_temp_dir() . '/composer-update-helper-plugin-test-' . uniqid();
         $vendorDir  = $tempDir . '/vendor';
@@ -224,6 +226,7 @@ public function testInstallFilesSkipsWhenFileExists(): void
         // Create existing file with different content
         $existingContent = '#!/bin/sh\necho "old"';
         file_put_contents($tempDir . '/generate-composer-require.sh', $existingContent);
+        file_put_contents($tempDir . '/composer.json', json_encode(['name' => 'test/project'], JSON_THROW_ON_ERROR));
 
         // Create source file in package with new content
         $sourceFile = $binDir . '/generate-composer-require.sh';
@@ -239,16 +242,9 @@ public function testInstallFilesSkipsWhenFileExists(): void
             ->willReturn($config);
 
         $io = $this->createMock(IOInterface::class);
-        // When content differs, file should be updated
-        // Allow any of these messages (at least one must appear)
-        $io->expects($this->atLeastOnce())
+        $io->expects($this->once())
             ->method('write')
-            ->with($this->logicalOr(
-                $this->stringContains('Updating generate-composer-require.sh'),
-                $this->stringContains('Creating generate-composer-require.yaml'),
-                $this->stringContains('Updated .gitignore'),
-                $this->stringContains('updated .gitignore'),
-            ));
+            ->with($this->stringContains('auto_update_wrapper'));
 
         $event = $this->createMock(Event::class);
         $event->method('getIO')
@@ -258,13 +254,71 @@ public function testInstallFilesSkipsWhenFileExists(): void
         $plugin->activate($composer, $io);
         $plugin->onPostInstall($event);
 
-        // File should be updated with new content
+        // File should be preserved when auto-update is not enabled
         $this->assertFileExists($tempDir . '/generate-composer-require.sh');
-        $this->assertStringContainsString('new', (string) file_get_contents($tempDir . '/generate-composer-require.sh'));
+        $this->assertStringContainsString('old', (string) file_get_contents($tempDir . '/generate-composer-require.sh'));
 
         // Cleanup
+        @unlink($tempDir . '/composer.json');
         @unlink($tempDir . '/generate-composer-require.sh');
         @unlink($tempDir . '/generate-composer-require.yaml');
+        @rmdir($binDir);
+        @rmdir($packageDir);
+        @rmdir($vendorDir);
+        @rmdir($tempDir);
+    }
+
+    public function testInstallFilesUpdatesWhenAutoUpdateWrapperEnabled(): void
+    {
+        $tempDir    = sys_get_temp_dir() . '/composer-update-helper-plugin-test-' . uniqid();
+        $vendorDir  = $tempDir . '/vendor';
+        $packageDir = $vendorDir . '/nowo-tech/composer-update-helper';
+        $binDir     = $packageDir . '/bin';
+        mkdir($binDir, 0777, true);
+
+        $existingContent = '#!/bin/sh\necho "old"';
+        file_put_contents($tempDir . '/generate-composer-require.sh', $existingContent);
+        file_put_contents($tempDir . '/composer.json', json_encode([
+            'name'  => 'test/project',
+            'extra' => [
+                'composer-update-helper' => [
+                    'auto_update_wrapper' => true,
+                ],
+            ],
+        ], JSON_THROW_ON_ERROR));
+
+        $sourceFile = $binDir . '/generate-composer-require.sh';
+        file_put_contents($sourceFile, '#!/bin/sh\necho "new"');
+
+        $config = $this->createMock(Config::class);
+        $config->method('get')
+            ->with('vendor-dir')
+            ->willReturn($vendorDir);
+
+        $composer = $this->createMock(Composer::class);
+        $composer->method('getConfig')
+            ->willReturn($config);
+
+        $io = $this->createMock(IOInterface::class);
+        $io->expects($this->atLeastOnce())
+            ->method('write')
+            ->with($this->stringContains('Updating generate-composer-require.sh'));
+
+        $event = $this->createMock(Event::class);
+        $event->method('getIO')
+            ->willReturn($io);
+
+        $plugin = new Plugin();
+        $plugin->activate($composer, $io);
+        $plugin->onPostInstall($event);
+
+        $this->assertStringContainsString('new', (string) file_get_contents($tempDir . '/generate-composer-require.sh'));
+
+        @unlink($tempDir . '/composer.json');
+        @unlink($tempDir . '/generate-composer-require.sh');
+        @unlink($tempDir . '/generate-composer-require.yaml');
+        @rmdir($binDir);
+        @rmdir($packageDir);
         @rmdir($vendorDir);
         @rmdir($tempDir);
     }