Update galaxy.yml

bump version

.github/workflows/galaxy.yml

@@ -1,9 +1,8 @@
----
 name: Build and Publish Collection to Ansible Galaxy
 
-'on':
+on:
   release:
-    types: [ published ]
+    types: [published]
   workflow_dispatch:
 
 defaults:
@@ -12,44 +11,43 @@ defaults:
 
 jobs:
   release:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
-      - name: Checkout git repo
+      - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v5
         with:
           path: collections/ansible_collections/kewlfft/aur
 
-      - name: Ensure that `version:` in `galaxy.yml` matches `GITHUB_REF`
+      - name: Verify version in galaxy.yml matches release tag
-        id: version
         run: |
-          [ "$(cat galaxy.yml | grep version: | awk '{print $2}')" = $(awk -F '/' '{print substr($3, 2)}' <<< ${GITHUB_REF}) ] || exit 1
+          tag_version="${GITHUB_REF##*/}"   # strip refs/tags/
-          echo ::set-output name=version::$(awk -F '/' '{print substr($3, 2)}' <<< ${GITHUB_REF})
+          file_version=$(awk '/^version:/ {print $2}' galaxy.yml)
 
-      - name: "Set up Python 3.9"
+          if [ "$file_version" != "$tag_version" ]; then
-        uses: actions/setup-python@v2
+            echo "❌ galaxy.yml version ($file_version) does not match tag ($tag_version)"
+            exit 1
+          fi
+
+      - name: Build collection
+        run: |
+          path=$(ansible-galaxy collection build | awk '/Created collection/ {print $NF}')
+          echo "TARBALL=$path" >> $GITHUB_ENV
+          echo "📦 Built collection at $path"
+
+      - name: Upload built collection artifact
+        uses: actions/upload-artifact@v4
         with:
-          python-version: "3.9"
+          name: ansible-collection-tarball
+          path: ${{ env.TARBALL }}
 
-      - name: Generate cache keys
+      - name: Debug tarball before publish
-        id: keys
         run: |
-          echo ::set-output name=pip_cache_dir::$(pip cache dir)
+          echo "🔎 Checking tarball path..."
-          # This ensures that the cache is invalidated after a week
+          echo "TARBALL=$TARBALL"
-          echo ::set-output name=date::$(date +%Y_%g)
+          ls -l "$(dirname "$TARBALL")"
 
-      - name: Pip Cache
+      - name: Publish collection
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.keys.outputs.pip_cache_dir }}
-          key: ansible-pip-${{ steps.keys.outputs.date }}
-
-      - name: Install pip packages
         run: |
-          pip3 install -U pip
+          echo "📤 Publishing $TARBALL ..."
-          pip3 install wheel
+          ansible-galaxy collection publish "$TARBALL" \
-          pip3 install ansible-core
+            --api-key "${{ secrets.ANSIBLE_GALAXY_API_KEY }}"
-
-      - name: Deploy collection
-        run: |
-          ansible-galaxy collection build
-          ansible-galaxy collection publish --api-key ${{ secrets.GALAXY_API_KEY }} "./kewlfft-aur-${{ steps.version.outputs.version }}.tar.gz"

README.md

@@ -23,7 +23,7 @@ collections:
 
 ### Install the `kewlfft.aur` collection from the AUR
 
-The `kewlfft.aur` collection is also available in the AUR as the `ansible-collection-kewlfft-aur` package.
+The `kewlfft.aur` collection is also available in the AUR as the [`ansible-collection-kewlfft-aur`](https://aur.archlinux.org/packages/ansible-collection-kewlfft-aur/) package.
 
 ### Install the `kewlfft.aur` collection locally for development
 
@@ -67,8 +67,9 @@ The following helpers are supported and automatically selected, if present, in t
 | Parameter      | Choices/**Default**                                          | Comments                                                                                                                                     |
 | -------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | name           |                                                              | Name or list of names of the package(s) to install or upgrade.                                                                               |
-| state          | **present**, latest                                          | Desired state of the package, 'present' skips operations if the package is already installed.                                                |
+| state          | **present**, latest, absent                                          | Desired state of the package, 'present' skips operations if the package is already installed.                                                |
 | upgrade        | yes, **no**                                                  | Whether or not to upgrade whole system.                                                                                                      |
+| update_cache        | yes, **no**                                                  | Whether or not to refresh the packages cache |
 | use            | **auto**, yay, paru, pacaur, trizen, pikaur, aurman, makepkg | The tool to use, 'auto' uses the first known helper found and makepkg as a fallback.                                                         |
 | extra_args     | **null**                                                     | A list of additional arguments to pass directly to the tool. Cannot be used in 'auto' mode.                                                  |
 | aur_only       | yes, **no**                                                  | Limit helper operation to the AUR.                                                                                                           |
@@ -96,16 +97,19 @@ This user can be created in an Ansible task with the following actions:
 
 ```yaml
 - name: Create the `aur_builder` user
+  become: yes
   ansible.builtin.user:
     name: aur_builder
     create_home: yes
     group: wheel
 
 - name: Allow the `aur_builder` user to run `sudo pacman` without a password
+  become: yes
   ansible.builtin.lineinfile:
     path: /etc/sudoers.d/11-install-aur_builder
     line: 'aur_builder ALL=(ALL) NOPASSWD: /usr/bin/pacman'
     create: yes
+    mode: 0644
     validate: 'visudo -cf %s'
 ```
 
@@ -113,7 +117,7 @@ This user can be created in an Ansible task with the following actions:
 
 In order to use an Ansible module that is distributed in a collection, you must use its FQCN. This corresponds to "the full definition of a module, plugin, or role hosted within a collection, in the form `namespace.collection.content_name`" ([Source](https://github.com/ansible-collections/overview#terminology)). In this case, the `aur` module resides in the `aur` collection which is under the `kewlfft` namespace, so its FQCN is `kewlfft.aur.aur`.
 
-Please note that this does not apply if you installed the `aur` module as a local custom module. Do to the nature of local custom modules, you can simply use the module's short name: `aur`.
+Please note that this does not apply if you installed the `aur` module as a local custom module. Due to the nature of local custom modules, you can simply use the module's short name: `aur`.
 
 #### Examples
 
@@ -163,4 +167,14 @@ Use it in a task, as in the following examples:
     state: present
   become: yes
   become_user: aur_builder
-```
+
+# Remove AUR packages (state=absent)
+- name: Remove package_name_1 and package_name_2 using yay
+  kewlfft.aur.aur:
+    use: yay
+    state: absent
+    name:
+      - package_name_1
+      - package_name_2
+  become: yes
+  become_user: aur_builder

galaxy.yml

@@ -8,7 +8,7 @@ namespace: kewlfft
 name: aur
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 0.9.0
+version: 0.12.2
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md
@@ -65,5 +65,6 @@ issues: https://github.com/kewlfft/ansible-aur/issues
 # artifact. A pattern is matched from the relative path of the file or directory of the collection directory. This
 # uses 'fnmatch' to match the files or directories. Some directories and files like 'galaxy.yml', '*.pyc', '*.retry',
 # and '.git' are always filtered
-build_ignore: []
+build_ignore:
-
+  - .github
+  - .gitignore

plugins/modules/aur.py

@@ -31,7 +31,7 @@ options:
         description:
             - Desired state of the package.
         default: present
-        choices: [ present, latest ]
+        choices: [ present, latest, absent ]
 
     upgrade:
         description:
@@ -39,6 +39,12 @@ options:
         default: no
         type: bool
 
+    update_cache:
+        description:
+            - Whether or not to update_cache the package cache.
+        default: no
+        type: bool
+
     use:
         description:
             - The tool to use, 'auto' uses the first known helper found and makepkg as a fallback.
@@ -91,6 +97,14 @@ msg:
     description: action that has been taken
 helper:
     description: the helper that was actually used
+installed:
+    description: list of packages that were newly installed
+    returned: always
+    type: list
+updated:
+    description: list of packages that were upgraded
+    returned: always
+    type: list
 '''
 
 EXAMPLES = '''
@@ -117,6 +131,15 @@ use_cmd_local_pkgbuild = {
     'makepkg': ['makepkg', '--syncdeps', '--install', '--noconfirm', '--needed']
 }
 
+use_remove_cmd = {
+    'yay': ['yay', '-R', '--noconfirm'],
+    'paru': ['paru', '-R', '--noconfirm'],
+    'pacaur': ['pacaur', '-R', '--noconfirm'],
+    'trizen': ['trizen', '-R', '--noconfirm'],
+    'pikaur': ['pikaur', '-R', '--noconfirm'],
+    'aurman': ['aurman', '-R', '--noconfirm'],
+}
+
 has_aur_option = ['yay', 'paru', 'pacaur', 'trizen', 'pikaur', 'aurman']
 
 
@@ -132,18 +155,8 @@ def check_packages(module, packages):
     """
     Inform the user what would change if the module were run
     """
-    would_be_changed = []
+    would_be_changed = [package for package in packages if not package_installed(module, package)]
-    diff = {
+    diff = {'before': '', 'after': '\n'.join(package for package in would_be_changed if module._diff)}
-        'before': '',
-        'after': '',
-    }
-
-    for package in packages:
-        installed = package_installed(module, package)
-        if not installed:
-            would_be_changed.append(package)
-            if module._diff:
-                diff['after'] += package + "\n"
 
     if would_be_changed:
         status = True
@@ -160,7 +173,29 @@ def check_packages(module, packages):
     module.exit_json(changed=status, msg=message, diff=diff)
 
 
-def build_command_prefix(use, extra_args, skip_pgp_check=False, ignore_arch=False, aur_only=False, local_pkgbuild=None):
+def check_packages_absent(module, packages):
+    """
+    Inform the user what would change if the module were run with state=absent
+    """
+    would_be_changed = [package for package in packages if package_installed(module, package)]
+    diff = {'before': '\n'.join(pkg for pkg in would_be_changed if module._diff), 'after': ''}
+
+    if would_be_changed:
+        status = True
+        if len(packages) > 1:
+            message = '{} package(s) would be removed'.format(len(would_be_changed))
+        else:
+            message = 'package would be removed'
+    else:
+        status = False
+        if len(packages) > 1:
+            message = 'all packages are already absent'
+        else:
+            message = 'package is already absent'
+    module.exit_json(changed=status, msg=message, diff=diff)
+
+
+def build_command_prefix(use, extra_args, skip_pgp_check=False, ignore_arch=False, aur_only=False, local_pkgbuild=None, update_cache=False):
     """
     Create the prefix of a command that can be used by the install and upgrade functions.
     """
@@ -176,6 +211,8 @@ def build_command_prefix(use, extra_args, skip_pgp_check=False, ignore_arch=Fals
         command.append('--aur')
     if local_pkgbuild and use != 'makepkg':
         command.append(local_pkgbuild)
+    if update_cache:
+        command.append('-y')
     if extra_args:
         command += shlex.split(extra_args)
     return command
@@ -223,22 +260,21 @@ def check_upgrade(module, use):
     Inform user how many packages would be upgraded
     """
     rc, stdout, stderr = module.run_command([use, '-Qu'], check_rc=True)
-    data = stdout.split('\n')
+    num_packages = sum(1 for line in stdout.splitlines() if line.strip())
-    data.remove('')
     module.exit_json(
-        changed=len(data) > 0,
+        changed=num_packages > 0,
-        msg="{} package(s) would be upgraded".format(len(data)),
+        msg=f"{num_packages} package(s) would be upgraded",
         helper=use,
     )
 
 
-def upgrade(module, use, extra_args, aur_only):
+def upgrade(module, use, extra_args, aur_only, update_cache):
     """
     Upgrade the whole system
     """
     assert use in use_cmd
 
-    command = build_command_prefix(use, extra_args, aur_only=aur_only)
+    command = build_command_prefix(use, extra_args, aur_only=aur_only, update_cache=update_cache)
     command.append('-u')
 
     rc, out, err = module.run_command(command, check_rc=True)
@@ -250,7 +286,7 @@ def upgrade(module, use, extra_args, aur_only):
     )
 
 
-def install_packages(module, packages, use, extra_args, state, skip_pgp_check, ignore_arch, aur_only, local_pkgbuild):
+def install_packages(module, packages, use, extra_args, state, skip_pgp_check, ignore_arch, aur_only, local_pkgbuild, update_cache):
     """
     Install the specified packages
     """
@@ -259,11 +295,12 @@ def install_packages(module, packages, use, extra_args, state, skip_pgp_check, i
     else:
         assert use in use_cmd
 
-    changed_iter = False
+    installed_pkgs = []
+    updated_pkgs = []
 
     for package in packages:
-        if state == 'present':
+        was_installed = package_installed(module, package)
-            if package_installed(module, package):
+        if state == 'present' and was_installed:
             rc = 0
             continue
         if use == 'makepkg':
@@ -271,11 +308,18 @@ def install_packages(module, packages, use, extra_args, state, skip_pgp_check, i
         elif local_pkgbuild:
             rc, out, err = install_local_package(module, package, use, extra_args, local_pkgbuild)
         else:
-            command = build_command_prefix(use, extra_args, aur_only=aur_only)
+            command = build_command_prefix(use, extra_args, aur_only=aur_only, update_cache=update_cache)
             command.append(package)
             rc, out, err = module.run_command(command, check_rc=True)
 
-        changed_iter = changed_iter or not (out == '' or '-- skipping' in out or 'nothing to do' in out.lower())
+        changed_pkg = not (out == '' or 'up-to-date -- skipping' in out or 'nothing to do' in out.lower())
+        if changed_pkg:
+            if was_installed:
+                updated_pkgs.append(package)
+            else:
+                installed_pkgs.append(package)
+
+    changed_iter = bool(installed_pkgs or updated_pkgs)
 
     message = 'installed package(s)' if changed_iter else 'package(s) already installed'
 
@@ -284,6 +328,46 @@ def install_packages(module, packages, use, extra_args, state, skip_pgp_check, i
         msg=message if not rc else err,
         helper=use,
         rc=rc,
+        installed=installed_pkgs,
+        updated=updated_pkgs,
+    )
+
+
+def remove_packages(module, packages, use, extra_args):
+    """
+    Remove the specified packages
+    """
+    # Determine the base command. If a helper other than makepkg is selected, use it.
+    # If use is 'makepkg' (which has no remove capability), fallback to pacman directly.
+    def base_remove_cmd(selected_use):
+        if selected_use == 'makepkg':
+            return def_lang + ['pacman', '-R', '--noconfirm'], 'pacman'
+        else:
+            assert selected_use in use_remove_cmd
+            return def_lang + use_remove_cmd[selected_use], selected_use
+
+    changed_iter = False
+    rc = 0
+    used_helper = use
+
+    for package in packages:
+        if not package_installed(module, package):
+            continue
+        command, helper = base_remove_cmd(use)
+        used_helper = helper
+        if extra_args:
+            command += shlex.split(extra_args)
+        command.append(package)
+        rc, out, err = module.run_command(command, check_rc=True)
+        changed_iter |= (rc == 0)
+
+    message = 'removed package(s)' if changed_iter else 'package(s) already absent'
+
+    module.exit_json(
+        changed=changed_iter,
+        msg=message if not rc else err,
+        helper=used_helper,
+        rc=rc,
     )
 
 
@@ -295,11 +379,15 @@ def make_module():
             },
             'state': {
                 'default': 'present',
-                'choices': ['present', 'latest'],
+                'choices': ['present', 'latest', 'absent'],
             },
             'upgrade': {
                 'type': 'bool',
             },
+            'update_cache': {
+                'default': False,
+                'type': 'bool',
+            },
             'use': {
                 'default': 'auto',
                 'choices': ['auto'] + list(use_cmd.keys()),
@@ -372,10 +460,19 @@ def apply_module(module, use):
         if module.check_mode:
             check_upgrade(module, use)
         else:
-            upgrade(module, use, params['extra_args'], params['aur_only'])
+            upgrade(module, use, params['extra_args'], params['aur_only'], params['update_cache'])
     else:
         if module.check_mode:
+            if params['state'] == 'absent':
+                check_packages_absent(module, params['name'])
+            else:
                 check_packages(module, params['name'])
+        else:
+            if params['state'] == 'absent':
+                remove_packages(module,
+                                params['name'],
+                                use,
+                                params['extra_args'])
             else:
                 install_packages(module,
                                  params['name'],
@@ -385,7 +482,8 @@ def apply_module(module, use):
                                  params['skip_pgp_check'],
                                  params['ignore_arch'],
                                  params['aur_only'],
-                             params['local_pkgbuild'])
+                                 params['local_pkgbuild'],
+                                 params['update_cache'])
 
 
 def main():