gem - fix --user-install conflict with OS-injected --install-dir (#11873)

* gem - fix --user-install conflict with OS-injected --install-dir

Some distributions (e.g. Fedora) inject --install-dir via operating_system.rb
as a platform default. Combining that with --user-install causes a gem CLI
parser error. Resolve the user install directory at install time and pass
--install-dir instead, which is semantically equivalent and avoids the conflict.
Uninstall is intentionally left unscoped so gem can find gems regardless of
where they were originally installed.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* gem - add changelog fragment for #11873

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* gem - fix user_install handling for install and uninstall

Two issues found in CI:

1. `gem environment user_gemhome` is not supported on older RubyGems (e.g.
   Ubuntu 20.04 ships 3.1.2). Simplify get_user_install_dir() to always parse
   the full `gem environment` output for "USER INSTALLATION DIRECTORY", which
   is stable across all supported versions.

2. On Fedora, `gem uninstall` without flags only searches the system gem path
   (set by operating_system.rb), so it cannot find gems installed to the user
   dir via --install-dir. Add user_install to the uninstall args_order so that
   gem uninstall --user-install is passed when user_install=True. The OS
   defaults conflict only applies to gem install, not gem uninstall.
   The integration test is updated to be consistent: the user_install:false
   install/remove block now also specifies user_install:false on removal.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* gem - use --install-dir for both install and uninstall of user gems

gem uninstall --user-install does not reliably find gems on Fedora/RHEL when
running as root, because those systems may disable user gem home for root and
Gem.user_dir may differ from the path resolved via 'gem environment'.

Use --install-dir <user_dir> for uninstall as well, since that is the exact
path used during install, making the operation consistent across platforms.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* gem - add override_platform_install_dir option and type hints

- add type hints to all functions
- fix misleading comment about --install-dir scoping for uninstall
- add override_platform_install_dir option (default=false) to opt in to
  resolving and passing the user gem dir explicitly to both gem install
  and gem uninstall, working around OS-injected platform defaults on
  distributions such as Fedora
- reclassify changelog fragment as minor_changes (new parameter, not
  backport-eligible)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(gem): add integration test for override_platform_install_dir

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(gem): skip default user_install test on RedHat family

OS-injected --install-dir on RHEL/Fedora makes the default user_install: true
case fail. The override_platform_install_dir block already covers the correct
path on those platforms.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

tests/integration/targets/gem/tasks/main.yml

@@ -30,23 +30,15 @@
       loop: "{{ test_packages }}"
       when: ansible_facts.distribution != "MacOSX"
 
-    - name: Install a gem
-      gem:
-        name: gist
-        state: present
-      register: install_gem_result
-      ignore_errors: true
+    # default user_install: skip on RedHat/Fedora where OS-injected --install-dir conflicts
+    - when: ansible_facts.os_family != "RedHat"
+      block:
+        - name: Install a gem (default user_install)
+          gem:
+            name: gist
+            state: present
+          register: install_gem_result
 
-    # when running as root on Fedora, '--install-dir' is set in the os defaults which is
-    # incompatible with '--user-install', we ignore this error for this case only
-    - name: fail if failed to install gem
-      fail:
-        msg: "failed to install gem: {{ install_gem_result.msg }}"
-      when:
-        - install_gem_result is failed
-        - not (ansible_facts.user_uid == 0 and "User --install-dir or --user-install but not both" not in install_gem_result.msg)
-
-    - block:
         - name: List gems
           command: gem list
           register: current_gems
@@ -72,7 +64,6 @@
             that:
               - remove_gem_results is changed
               - current_gems.stdout is not search('gist\s+\([0-9.]+\)')
-      when: not install_gem_result is failed
 
     # install gem in --no-user-install
     - block:
@@ -97,6 +88,7 @@
           gem:
             name: gist
             state: absent
+            user_install: false
           register: remove_gem_results
 
         - name: List gems
@@ -179,7 +171,7 @@
         state: present
         bindir: "{{ remote_tmp_dir }}/custom_bindir"
         norc: true
-        user_install: false  # Avoid conflicts between --install-dir and --user-install when running as root on CentOS / Fedora / RHEL
+        user_install: false
       register: install_gem_result
 
     - name: Get stats of gem executable
@@ -199,7 +191,7 @@
         state: absent
         bindir: "{{ remote_tmp_dir }}/custom_bindir"
         norc: true
-        user_install: false  # Avoid conflicts between --install-dir and --user-install when running as root on CentOS / Fedora / RHEL
+        user_install: false
       register: install_gem_result
 
     - name: Get stats of gem executable
@@ -213,6 +205,53 @@
           - install_gem_result is changed
           - not gem_bindir_stat.stat.exists
 
+    # override_platform_install_dir: install and remove using explicit user gem dir
+    - name: Install a gem with override_platform_install_dir
+      gem:
+        name: gist
+        state: present
+        override_platform_install_dir: true
+      register: install_gem_result
+
+    - name: List gems
+      command: gem list
+      register: current_gems
+
+    - name: Ensure gem was installed with override_platform_install_dir
+      assert:
+        that:
+          - install_gem_result is changed
+          - current_gems.stdout is search('gist\s+\([0-9.]+\)')
+
+    - name: Install a gem with override_platform_install_dir (idempotency)
+      gem:
+        name: gist
+        state: present
+        override_platform_install_dir: true
+      register: install_gem_result
+
+    - name: Ensure install is idempotent
+      assert:
+        that:
+          - install_gem_result is not changed
+
+    - name: Remove a gem with override_platform_install_dir
+      gem:
+        name: gist
+        state: absent
+        override_platform_install_dir: true
+      register: remove_gem_result
+
+    - name: List gems
+      command: gem list
+      register: current_gems
+
+    - name: Verify gem was removed with override_platform_install_dir
+      assert:
+        that:
+          - remove_gem_result is changed
+          - current_gems.stdout is not search('gist\s+\([0-9.]+\)')
+
     - name: Attempt to uninstall default gem 'json'
       community.general.gem:
         name: json