start developing module for go_install

not going to be used for a long time
Making pkg tasks truly single file

library/go_install.py

@@ -0,0 +1,141 @@
+#!/usr/bin/python
+
+# Copyright: (c) 2026, Matthew Stobbs <matthew@sprouting.cloud>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = r'''
+---
+module: go_install
+
+short_description: Manage the installation and removal of go packages
+description: Manage the installation and removal of go packages using `go install`
+
+options:
+    name:
+        description:
+            - Name of the go package without the module part.
+            - This is the name of the executable that is installed in `bin`.
+        required: true
+        type: str
+    module:
+        description:
+            - The full module name (example.org/path/to/module)
+            - Only required if state != 'absent'
+        required: false
+        type: str
+    version:
+        description:
+            - The version of the module to install.
+            - Do not set this to '/v2' if you are using a '/v2' module, normally just latest.
+            - Defaults to 'latest'
+        required: false
+        type: str
+    state:
+        description:
+            - One of either 'present', 'latest' or 'absent'.
+            - Defaults to 'present'
+        require: false
+        type: str
+author:
+    - Matthew Stobbs <matthew@sprouting.cloud>
+'''
+
+EXAMPLES = r'''
+# Install the 'air' package at the latest version
+- name: Install package 'air'
+  go_install:
+    name: air
+    module: github.com/air-verse/air
+    state: latest
+
+# Remove the 'air' package
+- name: Install package 'air'
+  go_install:
+    name: air
+    state: absent
+
+# Install the 'pgx' package of /v5
+- name: Install package 'pgx'
+  go_install:
+    name: pgx
+    module: github.com/jackc/pgx/v5
+
+# Install the 'templ' package at a specific version
+- name: Install package 'templ' at version 0.3.906
+  go_install:
+    name: templ
+    module: github.com/a-h/templ/cmd/templ
+    version: v0.3.906
+'''
+
+RETURN = r'''
+# After installing air
+result: "installed github.com/air-verse/air@latest to /usr/local/bin/air"
+
+# After removing air
+result: "removed /usr/local/bin/air"
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+
+def run_module():
+    # define available arguments/parameters a user can pass to the module
+    module_args = dict(
+        name=dict(type='str', required=True),
+        module=dict(type='str', required=False, default="")
+        version=dict(type='str', required=False, default="latest")
+        state=dict(type='str', required=False, default="present")
+    )
+
+    # seed the result dict in the object
+    # we primarily care about changed and state
+    # changed is if this module effectively modified the target
+    # state will include any data that you want your module to pass back
+    # for consumption, for example, in a subsequent task
+    result = dict(
+        changed=False,
+        result=''
+    )
+
+    # the AnsibleModule object will be our abstraction working with Ansible
+    # this includes instantiation, a couple of common attr would be the
+    # args/params passed to the execution, as well as if the module
+    # supports check mode
+    module = AnsibleModule(
+        argument_spec=module_args,
+        supports_check_mode=True
+    )
+
+    # if the user is working with this module in only check mode we do not
+    # want to make any changes to the environment, just return the current
+    # state with no modifications
+    if module.check_mode:
+        module.exit_json(**result)
+
+    # manipulate or modify the state as needed (this is going to be the
+    # part where your module will do what it needs to do)
+    result['result'] = module.params['name']
+
+    # use whatever logic you need to determine whether or not this module
+    # made any modifications to your target
+    if module.params['new']:
+        result['changed'] = True
+
+    # during the execution of the module, if there is an exception or a
+    # conditional state that effectively causes a failure, run
+    # AnsibleModule.fail_json() to pass in the message and the result
+    if module.params['name'] == 'fail me':
+        module.fail_json(msg='You requested this to fail', **result)
+
+    # in the event of a successful module execution, you will want to
+    # simple AnsibleModule.exit_json(), passing the key/value results
+    module.exit_json(**result)
+
+
+def main():
+    run_module()
+
+if __name__ == '__main__':
+    main()