feat: add dynamic plugins factory usability enhancements

.cursor/rules/development-workflow.mdc

@@ -3,3 +3,10 @@ description: Development workflow commands and processes for the rhdh-dynamic-pl
 globs:
 alwaysApply: true
 ---
+
+## Dependency Management
+
+When adding new Python dependencies:
+1. Install using the `.venv` virtual environment: `.venv/bin/pip install <package>`
+2. Update `requirements.txt` (runtime deps) or `requirements.dev.txt` (dev/test deps) to reflect the change
+3. Verify the installed version matches what is recorded in the requirements file

.cursor/rules/integration-tests.mdc

@@ -44,7 +44,7 @@ def test_full_config_flow(self, make_config):
 
 ## Container E2E Tests
 
-> **Note:** E2E tests are not yet implemented. The `tests/e2e/` directory does not exist. The following guidance is for future implementation.
+> E2E tests are implemented in `tests/e2e/`. The `E2E_IMAGE` env var is **required** (no default fallback).
 
 - **Location**: `tests/e2e/`.
 - **Goal**: Validate that the container image works correctly with the provided `examples/`.

.cursor/rules/pytest-unit-tests.mdc

@@ -7,7 +7,7 @@ globs: tests/test_*.py
 ## General Principles
 - All unit tests must reside in the `tests/` directory.
 - Use **class-based grouping** for tests (e.g., `class TestClassName:`).
-- One test file per module (e.g., `test_config.py` for `config.py`).
+- One test file per class or method group. For small modules, use `test_<module>.py`. When tests exceed ~300-400 lines, split into `test_<module>_<method_or_class>.py`.
 - Ensure **100% isolation**: No network calls, no real file system changes outside `tmp_path`, no system command execution.
 
 ## Test Structure
@@ -81,11 +81,15 @@ def test_with_registry_config(self, make_config):
 ```
 
 ## Naming Conventions
-- Files: `test_<module_name>.py`
+- Files: `test_<module_name>.py` for small modules, or `test_<module_name>_<method_or_class>.py` when a module's tests exceed ~300-400 lines
 - Classes: `Test<ClassName><MethodName>` (optional MethodName if grouping by method)
 - Functions: `test_<scenario_description>`
 
 ## Current Test Files
-- `test_config.py`: Tests for `PluginFactoryConfig` class (load_from_env, load_registry_config, apply_patches_and_overlays, export_plugins)
+- `test_cli.py`: Tests for CLI argument parsing (`create_parser`)
+- `test_config_load_from_env.py`: Tests for `PluginFactoryConfig.load_from_env` method
+- `test_config_registry.py`: Tests for `PluginFactoryConfig.load_registry_config` method
+- `test_config_patches_and_overlays.py`: Tests for `PluginFactoryConfig.apply_patches_and_overlays` method
+- `test_config_export_plugins.py`: Tests for `PluginFactoryConfig.export_plugins` method
 - `test_source_config.py`: Tests for `SourceConfig` class (from_file, clone_to_path)
 - `test_plugin_list_config.py`: Tests for `PluginListConfig` class (from_file, get_plugins, add_plugin, remove_plugin)

.github/actions/should-skip-build/action.yaml

@@ -18,6 +18,10 @@ inputs:
     description: 'Regex patterns to match files for skip logic (space, comma, or newline-separated)'
     required: false
     default: '\.md$'
+  pr-number:
+    description: 'PR number for first-build protection. When set, skips only if a pr-{number} image already exists in the registry.'
+    required: false
+    default: ''
 outputs:
   should_skip:
     description: 'Whether the build should be skipped (true/false)'
@@ -29,7 +33,7 @@ runs:
   using: 'composite'
   steps:
     - name: Install skopeo
-      if: inputs.check-image == 'true'
+      if: inputs.check-image == 'true' || inputs.pr-number != ''
       shell: bash
       run: |
         if ! command -v skopeo &> /dev/null; then
@@ -93,13 +97,26 @@ runs:
             ;;
 
           pull_request|pull_request_target)
-            echo "Pull request event detected"
-            if [ -n "${{ github.event.pull_request.base.sha }}" ]; then
-              # Find the merge base between PR base and HEAD
+            echo "Pull request event detected (action: ${{ github.event.action }})"
+
+            # For synchronize events, use incremental diff (since last push)
+            # to avoid rebuilding for non-build affecting commits in a PR.
+            # Fall back to full PR diff for opened/reopened or if incremental fails.
+            if [ "${{ github.event.action }}" = "synchronize" ] && [ -n "${{ github.event.before }}" ]; then
+              BEFORE_SHA="${{ github.event.before }}"
+              echo "Synchronize event — attempting incremental diff against previous HEAD: ${BEFORE_SHA}"
+              if CHANGED_FILES=$(git diff --name-only "${BEFORE_SHA}" HEAD 2>/dev/null); then
+                echo "Using incremental diff (since last push)"
+              else
+                echo "Warning: incremental diff failed (before SHA unreachable), falling back to full PR diff"
+                BASE_COMMIT=$(git merge-base ${{ github.event.pull_request.base.sha }} HEAD)
+                echo "Base commit (merge-base): $BASE_COMMIT"
+                CHANGED_FILES=$(git diff --name-only "$BASE_COMMIT" HEAD)
+              fi
+            elif [ -n "${{ github.event.pull_request.base.sha }}" ]; then
               BASE_COMMIT=$(git merge-base ${{ github.event.pull_request.base.sha }} HEAD)
               echo "Base commit (merge-base): $BASE_COMMIT"
               CHANGED_FILES=$(git diff --name-only "$BASE_COMMIT" HEAD)
-
             else
               echo "Warning: No PR base SHA available, skipping file check"
               echo "should_skip=${SHOULD_SKIP}" >> $GITHUB_OUTPUT
@@ -177,9 +194,36 @@ runs:
         done <<< "$CHANGED_FILES"
 
         if [ "$ALL_FILES_MATCH_PATTERN" = "true" ]; then
-          SHOULD_SKIP="true"
-          SKIP_REASON="All changed files match skip patterns: $FILE_PATTERNS"
-          echo "✓ All changed files match skip patterns - build will be skipped"
+          echo "✓ All changed files match skip patterns"
+
+          # First-build protection: when pr-number is set, only skip if a PR
+          # image already exists. This ensures the first build always runs so
+          # that e2e tests have an image to test against.
+          PR_NUMBER="${{ inputs.pr-number }}"
+          if [ -n "$PR_NUMBER" ]; then
+            echo ""
+            echo "::group::First-build protection — checking for existing PR image"
+            PR_IMAGE_TAG="docker://${{ inputs.registry }}/${{ inputs.image }}:pr-${PR_NUMBER}"
+            echo "Checking for PR image: ${PR_IMAGE_TAG}"
+
+            skopeo inspect "${PR_IMAGE_TAG}" &>/dev/null
+            PR_IMAGE_EXISTS=$?
+
+            if [ $PR_IMAGE_EXISTS -eq 0 ]; then
+              SHOULD_SKIP="true"
+              SKIP_REASON="All changed files match skip patterns and PR image pr-${PR_NUMBER} already exists"
+              echo "PR image exists - safe to skip build"
+            else
+              SHOULD_SKIP="false"
+              SKIP_REASON="All changed files match skip patterns but no PR image exists yet — first build needed for e2e tests"
+              echo "No PR image found - first build required"
+            fi
+            echo "::endgroup::"
+          else
+            SHOULD_SKIP="true"
+            SKIP_REASON="All changed files match skip patterns: $FILE_PATTERNS"
+            echo "Build will be skipped"
+          fi
         else
           echo "✗ Found ${#NON_MATCHING_FILES[@]} file(s) not matching skip patterns:"
           printf '  - %s\n' "${NON_MATCHING_FILES[@]}"