#!/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()