From 0230d3cc5fa58cc9fde0e6811900e10f3a03b80e Mon Sep 17 00:00:00 2001
From: Jayson Grace <jayson.e.grace@gmail.com>
Date: Tue, 20 Feb 2024 11:48:27 -0700
Subject: [PATCH] Refactored pre-commit hooks

**Added:**
- New pre-commit hook scripts for checking licenses, running Go tests,
  and running prettier.

**Changed:**
- Updated go-licenses.sh script to include new functions for license
  checking and vendoring.
- Modified go-vet.sh to simplify the vetting process for Go packages.
- Adjusted mdstyle.rb to allow longer lines in code blocks and tables.
- Renamed .yaml-lint.yaml to yamllint.yaml and added comment spacing rule.
- Updated .pre-commit-config.yaml to include new hooks and update
  existing ones.

**Fixed:**
- Removed unnecessary set -ex flags in go-no-replacement.sh and go-vet.sh
  to prevent verbose output.
---
 .hooks/generate-docs.sh                       |  51 +++++++
 .hooks/go-licenses.sh                         |  45 ++++++
 .hooks/go-no-replacement.sh                   |   1 -
 .hooks/go-vet.sh                              |  22 +--
 .hooks/linters/mdstyle.rb                     |   6 +-
 .../{.yaml-lint.yaml => yamllint.yaml}        |   2 +
 .hooks/prettier.sh                            |  38 +++++
 .hooks/run-go-tests.sh                        |  76 ++++++++++
 .pre-commit-config.yaml                       |  64 ++++----
 cmd/README.md                                 |  88 +++++++++++
 cmd/storedXSSDos.go                           |  71 ++++-----
 go.mod                                        |   2 +-
 magefiles/README.md                           | 138 ++++++++++++++++++
 magefiles/go.mod                              |  19 +--
 magefiles/go.sum                              |  52 +------
 magefiles/magefile.go                         | 119 ++++++++++++---
 magefiles/testing.go                          |  98 +++++++++++++
 magefiles/tmpl/README.md.tmpl                 |  78 ++++++++++
 18 files changed, 803 insertions(+), 167 deletions(-)
 create mode 100755 .hooks/generate-docs.sh
 create mode 100755 .hooks/go-licenses.sh
 rename .hooks/linters/{.yaml-lint.yaml => yamllint.yaml} (68%)
 create mode 100755 .hooks/prettier.sh
 create mode 100755 .hooks/run-go-tests.sh
 create mode 100644 cmd/README.md
 create mode 100644 magefiles/README.md
 create mode 100644 magefiles/testing.go
 create mode 100644 magefiles/tmpl/README.md.tmpl

diff --git a/.hooks/generate-docs.sh b/.hooks/generate-docs.sh
new file mode 100755
index 0000000..251e5b6
--- /dev/null
+++ b/.hooks/generate-docs.sh
@@ -0,0 +1,51 @@
+#!/bin/bash
+#
+# This script is a pre-commit hook that checks if the mage command is
+# installed and if not, prompts the user to install it. If mage is
+# installed, the script navigates to the repository root by calling the
+# `rr` function and runs the `mage generatepackagedocs` command.
+# This command generates documentation for all Go packages in the current
+# directory and its subdirectories by traversing the file tree and creating
+# a new README.md file in each directory containing a Go package.
+# The script also ensures the presence of a specific utility bash file
+# (bashutils.sh) and sources it if found. If the command fails, the commit
+# is stopped, and an error message is shown.
+set -e
+
+# Define the URL of bashutils.sh
+bashutils_url="https://raw.githubusercontent.com/l50/dotfiles/main/bashutils"
+
+# Define the local path of bashutils.sh
+bashutils_path="/tmp/bashutils"
+
+# Check if bashutils.sh exists locally
+if [[ ! -f "${bashutils_path}" ]]; then
+    # bashutils.sh doesn't exist locally, so download it
+    curl -s "${bashutils_url}" -o "${bashutils_path}"
+fi
+
+# Source bashutils
+# shellcheck source=/dev/null
+source "${bashutils_path}"
+
+rr || exit 1
+
+# Check if mage is installed
+if ! command -v mage > /dev/null 2>&1; then
+    echo -e "mage is not installed\n"
+    echo -e "Please install mage by running the following command:\n"
+    echo -e "go install github.com/magefile/mage@latest\n"
+    exit 1
+fi
+
+# Run the mage generatepackagedocs command
+mage generatepackagedocs
+# Catch the exit code
+exit_status=$?
+
+# If the exit code is not zero (i.e., the command failed),
+# then stop the commit and show an error message
+if [ $exit_status -ne 0 ]; then
+    echo "failed to generate package docs"
+    exit 1
+fi
diff --git a/.hooks/go-licenses.sh b/.hooks/go-licenses.sh
new file mode 100755
index 0000000..fc82f5e
--- /dev/null
+++ b/.hooks/go-licenses.sh
@@ -0,0 +1,45 @@
+#!/bin/bash
+
+# Function to check if go mod vendor should run or not
+run_vendor()
+             {
+    echo "Running go mod vendor..."
+    go mod vendor
+}
+
+# Function to check licenses
+check_licenses()
+                 {
+    action=$1
+
+    go install github.com/google/go-licenses@latest
+
+    # Decide action based on input
+    if [[ $action == "check_forbidden" ]]; then
+        echo "Checking for forbidden licenses..."
+        output=$(go-licenses check ./... 2> /dev/null)
+        if [[ "${output}" == *"ERROR: forbidden license found"* ]]; then
+            echo "Forbidden licenses found. Please remove them."
+            exit 1
+        else
+            echo "No forbidden licenses found."
+        fi
+    elif [[ $action == "output_csv" ]]; then
+        echo "Outputting licenses to csv..."
+        status=go-licenses csv ./... 2> /dev/null
+    elif [[ $action == "vendor" ]]; then
+        echo "Vendoring dependencies..."
+        run_vendor
+    fi
+}
+
+# Ensure input is provided
+if [[ $# -lt 1 ]]; then
+    echo "Incorrect number of arguments."
+    echo "Usage: $0 <licenses action>"
+    echo "Example: $0 check_forbidden"
+    exit 1
+fi
+
+# Run checks
+check_licenses "${1}"
diff --git a/.hooks/go-no-replacement.sh b/.hooks/go-no-replacement.sh
index 004b50b..54bbe99 100755
--- a/.hooks/go-no-replacement.sh
+++ b/.hooks/go-no-replacement.sh
@@ -1,5 +1,4 @@
 #!/bin/bash
-set -ex
 
 REPO=$(grep "url" .git/config)
 
diff --git a/.hooks/go-vet.sh b/.hooks/go-vet.sh
index 7853fbb..f3f88d8 100755
--- a/.hooks/go-vet.sh
+++ b/.hooks/go-vet.sh
@@ -1,19 +1,11 @@
 #!/bin/bash
-set -ex
+set -e
 
-pkg=$(go list ./...)
-for dir in */; do
-    if [[ "${dir}" != ".mage" ]] \
-                              && [[ "${dir}" != ".hooks/" ]] \
-                              && [[ "${dir}" != "config/" ]] \
-                              && [[ "${dir}" != "docs/" ]] \
-                              && [[ "${dir}" != "magefiles/" ]] \
-                              && [[ "${dir}" != "cmd/" ]] \
-                              && [[ "${dir}" != "bin/" ]] \
-                              && [[ "${dir}" != "images/" ]] \
-                              && [[ "${dir}" != "resources/" ]] \
-                              && [[ "${dir}" != "files/" ]] \
-                              && [[ "${dir}" != "logs/" ]]; then
-        go vet "${pkg}/${dir}"
+pkgs=$(go list ./...)
+
+for pkg in $pkgs; do
+    dir="$(basename "$pkg")/"
+    if [[ "${dir}" != .*/ ]] && [[ "${dir}" != "magefiles/" ]]; then
+        go vet "${pkg}"
     fi
 done
diff --git a/.hooks/linters/mdstyle.rb b/.hooks/linters/mdstyle.rb
index 23e6f9e..190fe1c 100644
--- a/.hooks/linters/mdstyle.rb
+++ b/.hooks/linters/mdstyle.rb
@@ -15,8 +15,9 @@
 # Override default parameters for some built-in rules.
 # https://github.com/markdownlint/markdownlint/blob/master/docs/creating_styles.md#parameters
 
-# Ignore line length in code blocks.
-rule 'MD013', :ignore_code_blocks => true
+exclude_tag :line_length
+# Allow long lines in code blocks and tables
+rule 'MD013', line_length: 120, ignore_code_blocks: true, tables: false
 
 #===============================================================================
 # Exclude the rules I disagree with.
@@ -27,6 +28,7 @@
 #   - second indent
 # * Another major bullet
 exclude_rule 'MD004' # Unordered list style
+
 exclude_rule 'MD007' # Unordered list indentation
 
 # Ordered lists are fine.
diff --git a/.hooks/linters/.yaml-lint.yaml b/.hooks/linters/yamllint.yaml
similarity index 68%
rename from .hooks/linters/.yaml-lint.yaml
rename to .hooks/linters/yamllint.yaml
index 0cac2ef..e07eb4a 100644
--- a/.hooks/linters/.yaml-lint.yaml
+++ b/.hooks/linters/yamllint.yaml
@@ -6,3 +6,5 @@ rules:
     max: 200
     level: warning
   truthy: false
+  comments:
+    min-spaces-from-content: 1
diff --git a/.hooks/prettier.sh b/.hooks/prettier.sh
new file mode 100755
index 0000000..535d335
--- /dev/null
+++ b/.hooks/prettier.sh
@@ -0,0 +1,38 @@
+#!/bin/bash
+set -exo pipefail
+
+# Check if npm is installed
+if ! [ -x "$(command -v npm)" ]; then
+    echo 'Error: npm is not installed.' >&2
+    exit 1
+else
+    # Check if Prettier is installed
+    if ! [ -x "$(command -v prettier)" ]; then
+        echo 'Error: Prettier is not installed.' >&2
+        echo 'Installing Prettier...'
+        npm install -g prettier
+    fi
+fi
+
+# Check if Prettier is installed
+if ! [ -x "$(command -v prettier)" ]; then
+    echo 'Error: Prettier is not installed.' >&2
+    exit 1
+fi
+
+# Run Prettier on staged .json, .yaml, and .yml files
+echo "Running Prettier on staged files..."
+
+# List all staged files, filter for the desired extensions, and run Prettier
+git diff --cached --name-only --diff-filter=d \
+                                              | grep -E '\.(json|ya?ml)$' \
+                            | xargs -I {} prettier --write {}
+
+# Add the files back to staging area as Prettier may have modified them
+git diff --name-only --diff-filter=d \
+                                     | grep -E '\.(json|ya?ml)$' \
+                            | xargs git add
+
+echo "Prettier formatting completed."
+
+exit 0
diff --git a/.hooks/run-go-tests.sh b/.hooks/run-go-tests.sh
new file mode 100755
index 0000000..dedfd7b
--- /dev/null
+++ b/.hooks/run-go-tests.sh
@@ -0,0 +1,76 @@
+#!/bin/bash
+
+set -e
+
+TESTS_TO_RUN=$1
+RETURN_CODE=0
+
+TIMESTAMP=$(date +"%Y%m%d%H%M%S")
+LOGFILE="/tmp/goutils-unit-test-results-$TIMESTAMP.log"
+MODULE_ROOT=$(go list -m -f "{{.Dir}}")
+
+if [[ -z "${TESTS_TO_RUN}" ]]; then
+    echo "No tests input" | tee -a "$LOGFILE"
+    echo "Example - Run all shorter collection of tests: bash run-go-tests.sh short" | tee -a "$LOGFILE"
+    echo "Example - Run all tests: bash run-go-tests.sh all" | tee -a "$LOGFILE"
+    echo "Example - Run coverage for a specific version: bash run-go-tests.sh coverage" | tee -a "$LOGFILE"
+    echo "Example - Run tests for modified files: bash run-go-tests.sh modified" | tee -a "$LOGFILE"
+    exit 1
+fi
+
+run_tests()
+            {
+    local coverage_file=$1
+    repo_root=$(git rev-parse --show-toplevel 2> /dev/null) || exit
+    pushd "${repo_root}" || exit
+    echo "Logging output to ${LOGFILE}" | tee -a "$LOGFILE"
+    echo "Run the following command to see the output in real time:" | tee -a "$LOGFILE"
+    echo "tail -f ${LOGFILE}" | tee -a "$LOGFILE"
+    echo "Running tests..." | tee -a "$LOGFILE"
+
+    if [[ "${TESTS_TO_RUN}" == 'coverage' ]]; then
+        go test -v -race -failfast -tags=integration -coverprofile="${coverage_file}" ./... 2>&1 | tee -a "$LOGFILE"
+    elif [[ "${TESTS_TO_RUN}" == 'all' ]]; then
+        go test -v -race -failfast ./... 2>&1 | tee -a "$LOGFILE"
+    elif [[ "${TESTS_TO_RUN}" == 'short' ]] && [[ "${GITHUB_ACTIONS}" != "true" ]]; then
+        go test -v -short -failfast -race ./... 2>&1 | tee -a "$LOGFILE"
+    elif [[ "${TESTS_TO_RUN}" == 'modified' ]]; then
+        # Run tests for modified files
+        local modified_files
+        IFS=$'\n' read -r -a modified_files <<< "$(git diff --name-only --cached | grep '\.go$')"
+
+        local pkg_dirs=()
+
+        for file in "${modified_files[@]}"; do
+            local pkg_dir
+            pkg_dir=$(dirname "$file")
+            pkg_dir=${pkg_dir#"$MODULE_ROOT/"}
+            pkg_dirs+=("$pkg_dir")
+        done
+
+        # Remove duplicate package directories
+        IFS=$'\n' read -r -a pkg_dirs <<< "$(sort -u <<< "${pkg_dirs[*]}")"
+        unset IFS
+
+        for dir in "${pkg_dirs[@]}"; do
+            go test -v -race -failfast "./$dir/..." 2>&1 | tee -a "$LOGFILE"
+        done
+    else
+        if [[ "${GITHUB_ACTIONS}" != 'true' ]]; then
+            go test -v -failfast -race "./.../${TESTS_TO_RUN}" 2>&1 | tee -a "$LOGFILE"
+        fi
+    fi
+
+    RETURN_CODE=$?
+}
+
+if [[ "${TESTS_TO_RUN}" == 'coverage' ]]; then
+    run_tests 'coverage-all.out'
+else
+    run_tests
+fi
+
+if [[ "${RETURN_CODE}" -ne 0 ]]; then
+    echo "unit tests failed" | tee -a "$LOGFILE"
+    exit 1
+fi
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index d78fbce..0b1167c 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -5,39 +5,24 @@ repos:
     hooks:
       - id: check-case-conflict
       - id: check-merge-conflict
+      - id: check-symlinks
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: check-added-large-files
+      - id: detect-private-key
       - id: check-shebang-scripts-are-executable
 
   - repo: https://github.com/adrienverge/yamllint.git
-    rev: v1.32.0
+    rev: v1.35.1
     hooks:
       - id: yamllint
-        entry: yamllint --strict -c .hooks/linters/.yaml-lint.yaml
-
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.3
-    hooks:
-      - id: prettier
-        files: \.(json|md|yaml|yml)$
-
-  - repo: https://github.com/jumanjihouse/pre-commit-hooks
-    rev: 3.0.0
-    hooks:
-      - id: script-must-have-extension
-        name: Ensure shell scripts end with .sh
-        types: [shell]
-      - id: shellcheck
-      - id: shfmt
-      # Configuration in .mdlrc and .hooks/linters/mdstyle.rb
-      - id: markdownlint
+        entry: yamllint --strict -c .hooks/linters/yamllint.yaml
 
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:
       - id: codespell
-        entry: codespell -q 3 -f --skip=".git,.github" README.md cmd/*
+        entry: codespell -q 3 -f --skip=".git,.github,go.*,magefiles/go.*" README.md
 
   - repo: https://github.com/dnephin/pre-commit-golang
     rev: v0.5.1
@@ -46,12 +31,25 @@ repos:
       - id: go-lint
       - id: go-imports
       - id: go-cyclo
-        args: [-over=20]
+        args: [-over=15]
       - id: golangci-lint
       - id: go-critic
       - id: go-build
       - id: go-mod-tidy
 
+  - repo: https://github.com/jumanjihouse/pre-commit-hooks
+    rev: 3.0.0
+    hooks:
+      - id: script-must-have-extension
+        name: Ensure shell scripts end with .sh
+        types: [shell]
+        exclude: .bats
+      - id: shellcheck
+      - id: shfmt
+      # Configuration in .mdlrc and .hooks/linters/mdstyle.rb
+      - id: markdownlint
+        exclude: README.md
+
   - repo: local
     hooks:
       - id: go-no-replacement
@@ -60,14 +58,30 @@ repos:
         language: script
         files: go.mod
 
+      - id: go-unit-tests
+        name: Go unit tests
+        language: script
+        entry: .hooks/run-go-tests.sh modified
+        files: '\.go$'
+        pass_filenames: true
+
       - id: go-vet
         name: Run go vet
         language: script
         entry: .hooks/go-vet.sh
         files: '\.go$'
+        always_run: true
+        pass_filenames: true
+        require_serial: true
+        log_file: /tmp/go-vet.log
 
-      - id: go-unit-tests
-        name: Go unit tests
+      - id: go-licenses
+        name: Run go-licenses
         language: script
-        entry: .hooks/go-unit-tests.sh all
-        files: '\.go$'
+        entry: .hooks/go-licenses.sh check_forbidden
+
+      - id: prettier
+        name: Run prettier
+        entry: .hooks/prettier-hook.sh
+        language: script
+        types: [json, yaml]
diff --git a/cmd/README.md b/cmd/README.md
new file mode 100644
index 0000000..c385e5f
--- /dev/null
+++ b/cmd/README.md
@@ -0,0 +1,88 @@
+# caldera-security-tests/cmd
+
+The `cmd` package is a collection of utility functions
+designed to simplify common cmd tasks.
+
+---
+
+## Table of contents
+
+- [Functions](#functions)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Tests](#tests)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Functions
+
+### Execute()
+
+```go
+Execute()
+```
+
+Execute adds child commands to the root
+command and sets flags appropriately.
+
+---
+
+### Wait(float64)
+
+```go
+Wait(float64) time.Duration
+```
+
+Wait is used to wait for a period
+of time.
+
+---
+
+## Installation
+
+To use the caldera-security-tests/cmd package, you first need to install it.
+Follow the steps below to install via go get.
+
+```bash
+go get github.com/l50/goutils/v2/cmd
+```
+
+---
+
+## Usage
+
+After installation, you can import the package in your Go project
+using the following import statement:
+
+```go
+import "github.com/l50/goutils/v2/cmd"
+```
+
+---
+
+## Tests
+
+To ensure the package is working correctly, run the following
+command to execute the tests for `caldera-security-tests/cmd`:
+
+```bash
+go test -v
+```
+
+---
+
+## Contributing
+
+Pull requests are welcome. For major changes,
+please open an issue first to discuss what
+you would like to change.
+
+---
+
+## License
+
+This project is licensed under the MIT
+License - see the [LICENSE](../LICENSE)
+file for details.
diff --git a/cmd/storedXSSDos.go b/cmd/storedXSSDos.go
index bb01dee..a8782f1 100644
--- a/cmd/storedXSSDos.go
+++ b/cmd/storedXSSDos.go
@@ -1,25 +1,3 @@
-/*
-Copyright © 2022-present, Meta Platforms, Inc. and affiliates
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-*/
-
 package cmd
 
 import (
@@ -106,6 +84,33 @@ type Payload struct {
 	Visibility         string `json:"visibility"`
 }
 
+func sendPayloadRequest(data Payload, sinkURL string, cookie *network.Cookie) error {
+	payloadBytes, err := json.Marshal(data)
+	if err != nil {
+		log.WithError(err).Error("failed to marshal payload")
+		return err
+	}
+	body := bytes.NewReader(payloadBytes)
+
+	req, err := http.NewRequest("POST", sinkURL, body)
+	if err != nil {
+		log.WithError(err).Error("failed to create request")
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Cookie", fmt.Sprintf("%s=%s", cookie.Name, cookie.Value))
+	req.Header.Set("User-Agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.5112.101 Safari/537.36")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		log.WithError(err).Error("failed to submit request")
+		return err
+	}
+	defer resp.Body.Close()
+
+	return nil
+}
+
 func storedXSSDosVuln(payload string) error {
 	var buf []byte
 	var res *runtime.RemoteObject
@@ -130,29 +135,9 @@ func storedXSSDosVuln(payload string) error {
 				return err
 			}
 			for _, cookie := range cookies {
-				payloadBytes, err := json.Marshal(data)
-				if err != nil {
-					log.WithError(err).Error("failed to marshal payload")
-					return err
-				}
-				body := bytes.NewReader(payloadBytes)
-
-				req, err := http.NewRequest("POST", sinkURL, body)
-				if err != nil {
-					log.WithError(err).Error("failed to create request")
+				if err := sendPayloadRequest(data, sinkURL, cookie); err != nil {
 					return err
 				}
-				req.Header.Set("Content-Type", "application/json")
-				req.Header.Set("Cookie", fmt.Sprintf("%s=%s", cookie.Name, cookie.Value))
-				req.Header.Set("User-Agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.5112.101 Safari/537.36")
-
-				resp, err := http.DefaultClient.Do(req)
-				if err != nil {
-					log.WithError(err).Error("failed to submit request")
-					return err
-				}
-				defer resp.Body.Close()
-
 			}
 
 			return nil
diff --git a/go.mod b/go.mod
index c7d6847..69c8afb 100644
--- a/go.mod
+++ b/go.mod
@@ -1,6 +1,6 @@
 module github.com/fbsamples/caldera-security-tests
 
-go 1.21
+go 1.22
 
 require (
 	github.com/bitfield/script v0.22.0
diff --git a/magefiles/README.md b/magefiles/README.md
new file mode 100644
index 0000000..489b73f
--- /dev/null
+++ b/magefiles/README.md
@@ -0,0 +1,138 @@
+# caldera-security-tests/magefiles
+
+`magefiles` provides utilities that would normally be managed
+and executed with a `Makefile`. Instead of being written in the make language,
+magefiles are crafted in Go and leverage the [Mage](https://magefile.org/) library.
+
+---
+
+## Table of contents
+
+- [Functions](#functions)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Functions
+
+### Compile(context.Context, string)
+
+```go
+Compile(context.Context, string) error
+```
+
+Compile Compiles caldera-security-tests for the input operating system.
+
+# Example:
+```
+./magefile compile darwin
+```
+
+If an operating system is not input, binaries will be created for
+windows, linux, and darwin.
+
+---
+
+### GeneratePackageDocs()
+
+```go
+GeneratePackageDocs() error
+```
+
+GeneratePackageDocs creates documentation for the various packages
+in the project.
+
+Example usage:
+
+```go
+mage generatepackagedocs
+```
+
+**Returns:**
+
+error: An error if any issue occurs during documentation generation.
+
+---
+
+### InstallDeps()
+
+```go
+InstallDeps() error
+```
+
+InstallDeps installs the Go dependencies necessary for developing
+on the project.
+
+Example usage:
+
+```go
+mage installdeps
+```
+
+**Returns:**
+
+error: An error if any issue occurs while trying to
+install the dependencies.
+
+---
+
+### RunPreCommit()
+
+```go
+RunPreCommit() error
+```
+
+RunPreCommit updates, clears, and executes all pre-commit hooks
+locally. The function follows a three-step process:
+
+First, it updates the pre-commit hooks.
+Next, it clears the pre-commit cache to ensure a clean environment.
+Lastly, it executes all pre-commit hooks locally.
+
+Example usage:
+
+```go
+mage runprecommit
+```
+
+**Returns:**
+
+error: An error if any issue occurs at any of the three stages
+of the process.
+
+---
+
+### RunTests()
+
+```go
+RunTests() error
+```
+
+RunTests executes all unit tests.
+
+Example usage:
+
+```go
+mage runtests
+```
+
+**Returns:**
+
+error: An error if any issue occurs while running the tests.
+
+---
+
+## Contributing
+
+Pull requests are welcome. For major changes,
+please open an issue first to discuss what
+you would like to change.
+
+---
+
+## License
+
+This project is licensed under the MIT
+License - see the [LICENSE](../LICENSE)
+file for details.
diff --git a/magefiles/go.mod b/magefiles/go.mod
index 78dfd7a..e18e2b1 100644
--- a/magefiles/go.mod
+++ b/magefiles/go.mod
@@ -1,11 +1,12 @@
 module magefile
 
-go 1.21
+go 1.22
 
 require (
 	github.com/fatih/color v1.16.0
-	github.com/l50/goutils v1.3.1
+	github.com/l50/goutils/v2 v2.2.2
 	github.com/magefile/mage v1.15.0
+	github.com/spf13/afero v1.11.0
 )
 
 require (
@@ -13,42 +14,30 @@ require (
 	github.com/Microsoft/go-winio v0.6.1 // indirect
 	github.com/ProtonMail/go-crypto v1.0.0 // indirect
 	github.com/bitfield/script v0.22.0 // indirect
-	github.com/cavaliergopher/grab/v3 v3.0.1 // indirect
 	github.com/cloudflare/circl v1.3.7 // indirect
 	github.com/cyphar/filepath-securejoin v0.2.4 // indirect
 	github.com/emirpasic/gods v1.18.1 // indirect
-	github.com/glendc/go-external-ip v0.1.0 // indirect
 	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
 	github.com/go-git/go-billy/v5 v5.5.0 // indirect
 	github.com/go-git/go-git/v5 v5.11.0 // indirect
-	github.com/go-ole/go-ole v1.2.6 // indirect
 	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
 	github.com/itchyny/gojq v0.12.14 // indirect
 	github.com/itchyny/timefmt-go v0.1.5 // indirect
 	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
 	github.com/kevinburke/ssh_config v1.2.0 // indirect
-	github.com/lufia/plan9stats v0.0.0-20230326075908-cb1d2100619a // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/otiai10/copy v1.14.0 // indirect
 	github.com/pjbgf/sha1cd v0.3.0 // indirect
-	github.com/power-devops/perfstat v0.0.0-20221212215047-62379fc7944b // indirect
 	github.com/sergi/go-diff v1.3.1 // indirect
-	github.com/shirou/gopsutil/v3 v3.24.1 // indirect
-	github.com/shoenig/go-m1cpu v0.1.6 // indirect
 	github.com/skeema/knownhosts v1.2.1 // indirect
-	github.com/tidwall/gjson v1.17.1 // indirect
-	github.com/tidwall/match v1.1.1 // indirect
-	github.com/tidwall/pretty v1.2.1 // indirect
-	github.com/tklauser/go-sysconf v0.3.13 // indirect
-	github.com/tklauser/numcpus v0.7.0 // indirect
 	github.com/xanzy/ssh-agent v0.3.3 // indirect
-	github.com/yusufpapurcu/wmi v1.2.3 // indirect
 	golang.org/x/crypto v0.19.0 // indirect
 	golang.org/x/mod v0.14.0 // indirect
 	golang.org/x/net v0.21.0 // indirect
 	golang.org/x/sync v0.6.0 // indirect
 	golang.org/x/sys v0.17.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
 	golang.org/x/tools v0.17.0 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 	mvdan.cc/sh/v3 v3.8.0 // indirect
diff --git a/magefiles/go.sum b/magefiles/go.sum
index deea553..69d291b 100644
--- a/magefiles/go.sum
+++ b/magefiles/go.sum
@@ -12,8 +12,6 @@ github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkY
 github.com/bitfield/script v0.22.0 h1:LA7QHuEsXMPD52YLtxWrlqCCy+9FOpzNYfsRHC5Gsrc=
 github.com/bitfield/script v0.22.0/go.mod h1:ms4w+9B8f2/W0mbsgWDVTtl7K94bYuZc3AunnJC4Ebs=
 github.com/bwesterb/go-ristretto v1.2.3/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0=
-github.com/cavaliergopher/grab/v3 v3.0.1 h1:4z7TkBfmPjmLAAmkkAZNX/6QJ1nNFdv3SdIHXju0Fr4=
-github.com/cavaliergopher/grab/v3 v3.0.1/go.mod h1:1U/KNnD+Ft6JJiYoYBAimKH2XrYptb8Kl3DFGmsjpq4=
 github.com/cloudflare/circl v1.3.3/go.mod h1:5XYMA4rFBvNIrhs50XuiBJ15vF2pZn4nnUKZrLbUZFA=
 github.com/cloudflare/circl v1.3.7 h1:qlCDlTPz2n9fu58M0Nh1J/JzcFpfgkFHHX3O35r5vcU=
 github.com/cloudflare/circl v1.3.7/go.mod h1:sRTcRWXGLrKw6yIGJ+l7amYJFfAXbZG0kBSc8r4zxgA=
@@ -33,8 +31,6 @@ github.com/fatih/color v1.16.0/go.mod h1:fL2Sau1YI5c0pdGEVCbKQbLXB6edEj1ZgiY4Nij
 github.com/frankban/quicktest v1.14.4/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
-github.com/glendc/go-external-ip v0.1.0 h1:iX3xQ2Q26atAmLTbd++nUce2P5ht5P4uD4V7caSY/xg=
-github.com/glendc/go-external-ip v0.1.0/go.mod h1:CNx312s2FLAJoWNdJWZ2Fpf5O4oLsMFwuYviHjS4uJE=
 github.com/gliderlabs/ssh v0.3.5 h1:OcaySEmAQJgyYcArR+gGGTHCyE7nvhEMTlYY+Dp8CpY=
 github.com/gliderlabs/ssh v0.3.5/go.mod h1:8XB4KraRrX39qHhT6yxPsHedjA08I/uBVwj4xC+/+z4=
 github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 h1:+zs/tPmkDkHx3U66DAb0lQFJrpS6731Oaa12ikc+DiI=
@@ -45,12 +41,9 @@ github.com/go-git/go-git-fixtures/v4 v4.3.2-0.20231010084843-55a94097c399 h1:eMj
 github.com/go-git/go-git-fixtures/v4 v4.3.2-0.20231010084843-55a94097c399/go.mod h1:1OCfN199q1Jm3HZlxleg+Dw/mwps2Wbk9frAWm+4FII=
 github.com/go-git/go-git/v5 v5.11.0 h1:XIZc1p+8YzypNr34itUfSvYJcv+eYdTnTvOZ2vD3cA4=
 github.com/go-git/go-git/v5 v5.11.0/go.mod h1:6GFcX2P3NM7FPBfpePbpLd21XxsgdAt+lKqXmCUiUCY=
-github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
-github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
 github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da h1:oI5xCqsCo564l8iNU+DwB5epxmsaqB+rhGL0m5jtYqE=
 github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da/go.mod h1:cIg4eruTrX1D+g88fzRXU5OdNfaM+9IcxsU14FzY7Hc=
 github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
@@ -71,11 +64,8 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/l50/goutils v1.3.1 h1:3F4DeV+mr8UKswI6zLN+Rh+iP2BwekuZs20mKaHTenE=
-github.com/l50/goutils v1.3.1/go.mod h1:Btct6TQgAsXwuWbOq3r/eaAJfwb6FTnxpPjB8DkfDD4=
-github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
-github.com/lufia/plan9stats v0.0.0-20230326075908-cb1d2100619a h1:N9zuLhTvBSRt0gWSiJswwQ2HqDmtX/ZCDJURnKUt1Ik=
-github.com/lufia/plan9stats v0.0.0-20230326075908-cb1d2100619a/go.mod h1:JKx41uQRwqlTZabZc+kILPrO/3jlKnQ2Z8b7YiVw5cE=
+github.com/l50/goutils/v2 v2.2.2 h1:scZmJzJN6osvnDIWyORfM9vLc+ud5ZW1R8APn4of4kU=
+github.com/l50/goutils/v2 v2.2.2/go.mod h1:noqahXK9l3PlpLymgIxnKqAP1gmZj1s+nl9k2lI1V4w=
 github.com/magefile/mage v1.15.0 h1:BvGheCMAsG3bWUDbZ8AyXXpCNwU9u5CB6sM+HNb9HYg=
 github.com/magefile/mage v1.15.0/go.mod h1:z5UZb/iS3GoOSn0JgWuiw7dxlurVYTu+/jHXqQg881A=
 github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
@@ -98,9 +88,6 @@ github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
-github.com/power-devops/perfstat v0.0.0-20221212215047-62379fc7944b h1:0LFwY6Q3gMACTjAbMZBjXAqTOzOwFaj2Ld6cjeQ7Rig=
-github.com/power-devops/perfstat v0.0.0-20221212215047-62379fc7944b/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.4/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
@@ -109,42 +96,21 @@ github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU
 github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
 github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
 github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
-github.com/shirou/gopsutil/v3 v3.24.1 h1:R3t6ondCEvmARp3wxODhXMTLC/klMa87h2PHUw5m7QI=
-github.com/shirou/gopsutil/v3 v3.24.1/go.mod h1:UU7a2MSBQa+kW1uuDq8DeEBS8kmrnQwsv2b5O513rwU=
-github.com/shoenig/go-m1cpu v0.1.6 h1:nxdKQNcEB6vzgA2E2bvzKIYRuNj7XNJ4S/aRSwKzFtM=
-github.com/shoenig/go-m1cpu v0.1.6/go.mod h1:1JJMcUBvfNwpq05QDQVAnx3gUHr9IYF7GNg9SUEw2VQ=
-github.com/shoenig/test v0.6.4 h1:kVTaSd7WLz5WZ2IaoM0RSzRsUD+m8wRR+5qvntpn4LU=
-github.com/shoenig/test v0.6.4/go.mod h1:byHiCGXqrVaflBLAMq/srcZIHynQPQgeyvkvXnjqq0k=
 github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
 github.com/skeema/knownhosts v1.2.1 h1:SHWdIUa82uGZz+F+47k8SY4QhhI291cXCpopT1lK2AQ=
 github.com/skeema/knownhosts v1.2.1/go.mod h1:xYbVRSPxqBZFrdmDyMmsOs+uX1UZC3nTN3ThzgDxUwo=
+github.com/spf13/afero v1.11.0 h1:WJQKhtpdm3v2IzqG8VMqrr6Rf3UYpEF239Jy9wNepM8=
+github.com/spf13/afero v1.11.0/go.mod h1:GH9Y3pIexgf1MTIWtNGyogA5MwRIDXGUr+hbWNoBjkY=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
-github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.1 h1:4VhoImhV/Bm0ToFkXFi8hXNXwpDRZ/ynw3amt82mzq0=
+github.com/stretchr/objx v0.5.1/go.mod h1:/iHQpkQwBD6DLUmQ4pE+s1TXdob1mORJ4/UFdrifcy0=
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
-github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/tidwall/gjson v1.17.1 h1:wlYEnwqAHgzmhNUFfw7Xalt2JzQvsMx2Se4PcoFCT/U=
-github.com/tidwall/gjson v1.17.1/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
-github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
-github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
-github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
-github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
-github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
-github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
-github.com/tklauser/go-sysconf v0.3.13 h1:GBUpcahXSpR2xN01jhkNAbTLRk2Yzgggk8IM08lq3r4=
-github.com/tklauser/go-sysconf v0.3.13/go.mod h1:zwleP4Q4OehZHGn4CYZDipCgg9usW5IJePewFCGVEa0=
-github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
-github.com/tklauser/numcpus v0.7.0 h1:yjuerZP127QG9m5Zh/mSO4wqurYil27tHrqwRoRjpr4=
-github.com/tklauser/numcpus v0.7.0/go.mod h1:bb6dMVcj8A42tSE7i32fsIUCbQNllK5iDguyOZRUzAY=
 github.com/xanzy/ssh-agent v0.3.3 h1:+/15pJfg/RsTxqYcX6fHqOXZwwMP+2VyYWJeWM2qQFM=
 github.com/xanzy/ssh-agent v0.3.3/go.mod h1:6dzNDKs0J9rVPHPhaGCukekBHKqfl+L3KghI1Bc68Uw=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
-github.com/yusufpapurcu/wmi v1.2.3 h1:E1ctvB7uKFMOJw3fdOW32DwGE9I7t++CRUEMKvFoFiw=
-github.com/yusufpapurcu/wmi v1.2.3/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
@@ -171,10 +137,8 @@ golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.6.0 h1:5BMeUDZ7vkXGfEr1x9B4bRcTH4lpkTkpdh0T/J+qjbQ=
 golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
@@ -186,9 +150,6 @@ golang.org/x/sys v0.2.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.3.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.16.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.17.0 h1:25cE3gD+tdBA7lp7QfhuV+rJiE9YXTcS3VG1SqssI/Y=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
@@ -224,7 +185,6 @@ gopkg.in/warnings.v0 v0.1.2 h1:wFXVbFY8DY5/xOe1ECiWdKCzZlxgshcYVNkBHstARME=
 gopkg.in/warnings.v0 v0.1.2/go.mod h1:jksf8JmL6Qr/oQM2OXTHunEvvTAsrWBLb6OOjuVWRNI=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 mvdan.cc/editorconfig v0.2.0/go.mod h1:lvnnD3BNdBYkhq+B4uBuFFKatfp02eB6HixDvEz91C0=
diff --git a/magefiles/magefile.go b/magefiles/magefile.go
index 5a9ff7a..36b4fc9 100644
--- a/magefiles/magefile.go
+++ b/magefiles/magefile.go
@@ -9,10 +9,16 @@ import (
 	"path/filepath"
 
 	"github.com/fatih/color"
-	goutils "github.com/l50/goutils"
+	"github.com/l50/goutils/v2/dev/lint"
+	mageutils "github.com/l50/goutils/v2/dev/mage"
+	"github.com/l50/goutils/v2/docs"
+	"github.com/l50/goutils/v2/git"
+	"github.com/l50/goutils/v2/str"
+	"github.com/l50/goutils/v2/sys"
+	"github.com/spf13/afero"
 
 	// mage utility functions
-	"github.com/magefile/mage/mg"
+
 	"github.com/magefile/mage/sh"
 )
 
@@ -41,7 +47,7 @@ func Compile(ctx context.Context, osCli string) error {
 
 	if osCli == "all" {
 		operatingSystems = supportedOS
-	} else if goutils.StringInSlice(osCli, supportedOS) {
+	} else if str.InSlice(osCli, supportedOS) {
 		operatingSystems = []string{osCli}
 	}
 
@@ -73,21 +79,44 @@ func Compile(ctx context.Context, osCli string) error {
 	return nil
 }
 
-// InstallDeps Installs go dependencies
+// InstallDeps installs the Go dependencies necessary for developing
+// on the project.
+//
+// Example usage:
+//
+// ```go
+// mage installdeps
+// ```
+//
+// **Returns:**
+//
+// error: An error if any issue occurs while trying to
+// install the dependencies.
 func InstallDeps() error {
-	fmt.Println(color.YellowString("Installing dependencies."))
+	fmt.Println(color.YellowString("Running go mod tidy on magefiles and repo root."))
+	cwd := sys.Gwd()
+	if err := sys.Cd("magefiles"); err != nil {
+		return fmt.Errorf("failed to cd into magefiles directory: %v", err)
+	}
 
-	if err := goutils.Tidy(); err != nil {
-		return fmt.Errorf(color.RedString(
-			"failed to install dependencies: %v", err))
+	if err := mageutils.Tidy(); err != nil {
+		return fmt.Errorf("failed to install dependencies: %v", err)
 	}
 
-	if err := goutils.InstallGoPCDeps(); err != nil {
-		return fmt.Errorf(color.RedString(
-			"failed to install pre-commit dependencies: %v", err))
+	if err := sys.Cd(cwd); err != nil {
+		return fmt.Errorf("failed to cd back into repo root: %v", err)
 	}
 
-	if err := goutils.InstallVSCodeModules(); err != nil {
+	if err := mageutils.Tidy(); err != nil {
+		return fmt.Errorf("failed to install dependencies: %v", err)
+	}
+
+	fmt.Println(color.YellowString("Installing dependencies."))
+	if err := lint.InstallGoPCDeps(); err != nil {
+		return fmt.Errorf("failed to install pre-commit dependencies: %v", err)
+	}
+
+	if err := mageutils.InstallVSCodeModules(); err != nil {
 		return fmt.Errorf(color.RedString(
 			"failed to install vscode-go modules: %v", err))
 	}
@@ -95,24 +124,76 @@ func InstallDeps() error {
 	return nil
 }
 
-// RunPreCommit runs all pre-commit hooks locally
+// RunPreCommit updates, clears, and executes all pre-commit hooks
+// locally. The function follows a three-step process:
+//
+// First, it updates the pre-commit hooks.
+// Next, it clears the pre-commit cache to ensure a clean environment.
+// Lastly, it executes all pre-commit hooks locally.
+//
+// Example usage:
+//
+// ```go
+// mage runprecommit
+// ```
+//
+// **Returns:**
+//
+// error: An error if any issue occurs at any of the three stages
+// of the process.
 func RunPreCommit() error {
-	mg.Deps(InstallDeps)
+	if !sys.CmdExists("pre-commit") {
+		return fmt.Errorf("pre-commit is not installed")
+	}
+
 	fmt.Println(color.YellowString("Updating pre-commit hooks."))
-	if err := goutils.UpdatePCHooks(); err != nil {
+	if err := lint.UpdatePCHooks(); err != nil {
 		return err
 	}
 
-	fmt.Println(color.YellowString(
-		"Clearing the pre-commit cache to ensure we have a fresh start."))
-	if err := goutils.ClearPCCache(); err != nil {
+	fmt.Println(color.YellowString("Clearing the pre-commit cache to ensure we have a fresh start."))
+	if err := lint.ClearPCCache(); err != nil {
 		return err
 	}
 
 	fmt.Println(color.YellowString("Running all pre-commit hooks locally."))
-	if err := goutils.RunPCHooks(); err != nil {
+	if err := lint.RunPCHooks(); err != nil {
 		return err
 	}
 
 	return nil
 }
+
+// GeneratePackageDocs creates documentation for the various packages
+// in the project.
+//
+// Example usage:
+//
+// ```go
+// mage generatepackagedocs
+// ```
+//
+// **Returns:**
+//
+// error: An error if any issue occurs during documentation generation.
+func GeneratePackageDocs() error {
+	fs := afero.NewOsFs()
+
+	repoRoot, err := git.RepoRoot()
+	if err != nil {
+		return fmt.Errorf("failed to get repo root: %v", err)
+	}
+	sys.Cd(repoRoot)
+
+	repo := docs.Repo{
+		Owner: "l50",
+		Name:  "goutils/v2",
+	}
+
+	templatePath := filepath.Join("magefiles", "tmpl", "README.md.tmpl")
+	if err := docs.CreatePackageDocs(fs, repo, templatePath); err != nil {
+		return fmt.Errorf("failed to create package docs: %v", err)
+	}
+
+	return nil
+}
diff --git a/magefiles/testing.go b/magefiles/testing.go
new file mode 100644
index 0000000..39cb011
--- /dev/null
+++ b/magefiles/testing.go
@@ -0,0 +1,98 @@
+//go:build mage
+// +build mage
+
+package main
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/l50/goutils/v2/git"
+	"github.com/l50/goutils/v2/sys"
+)
+
+type compileParams struct {
+	GOOS   string
+	GOARCH string
+}
+
+var repoRoot string
+
+func init() {
+	var err error
+	repoRoot, err = git.RepoRoot()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to get repo root: %v", err)
+		os.Exit(1)
+	}
+}
+
+// RunTests executes all unit tests.
+//
+// Example usage:
+//
+// ```go
+// mage runtests
+// ```
+//
+// **Returns:**
+//
+// error: An error if any issue occurs while running the tests.
+func RunTests() error {
+	fmt.Println("Running unit tests.")
+	if _, err := sys.RunCommand(filepath.Join(".hooks", "run-go-tests.sh"), "all"); err != nil {
+		return fmt.Errorf("failed to run unit tests: %v", err)
+	}
+
+	return nil
+}
+
+// processLines parses an io.Reader, identifying and marking code blocks
+// found in a README.
+func processLines(r io.Reader, language string) ([]string, error) {
+	scanner := bufio.NewScanner(r)
+	var lines, codeBlockLines []string
+	var inCodeBlock bool
+
+	for scanner.Scan() {
+		line := scanner.Text()
+
+		inCodeBlock, codeBlockLines = handleLineInCodeBlock(strings.TrimSpace(line), line, inCodeBlock, language, codeBlockLines)
+
+		if !inCodeBlock {
+			lines = append(lines, codeBlockLines...)
+			codeBlockLines = codeBlockLines[:0]
+			if !strings.HasPrefix(line, "```") {
+				lines = append(lines, line)
+			}
+		}
+	}
+
+	if inCodeBlock {
+		codeBlockLines = append(codeBlockLines, "\t\t\t// ```")
+		lines = append(lines, codeBlockLines...)
+	}
+
+	return lines, scanner.Err()
+}
+
+// handleLineInCodeBlock categorizes and handles each line based on its
+// content and relation to code blocks found in a README.
+func handleLineInCodeBlock(trimmedLine, line string, inCodeBlock bool, language string, codeBlockLines []string) (bool, []string) {
+	switch {
+	case strings.HasPrefix(trimmedLine, "```"+language):
+		if !inCodeBlock {
+			codeBlockLines = append(codeBlockLines, line)
+		}
+		return !inCodeBlock, codeBlockLines
+	case inCodeBlock:
+		codeBlockLines = append(codeBlockLines, line)
+	case strings.Contains(trimmedLine, "```"):
+		inCodeBlock = false
+	}
+	return inCodeBlock, codeBlockLines
+}
diff --git a/magefiles/tmpl/README.md.tmpl b/magefiles/tmpl/README.md.tmpl
new file mode 100644
index 0000000..3f5c9a6
--- /dev/null
+++ b/magefiles/tmpl/README.md.tmpl
@@ -0,0 +1,78 @@
+# caldera-security-tests/{{.PackageName}}
+
+{{if ne .PackageName "magefiles"}}The `{{.PackageName}}` package is a collection of utility functions
+designed to simplify common {{.PackageName}} tasks.
+{{else}}`{{.PackageName}}` provides utilities that would normally be managed
+and executed with a `Makefile`. Instead of being written in the make language,
+magefiles are crafted in Go and leverage the [Mage](https://magefile.org/) library.
+{{end}}
+---
+
+## Table of contents
+
+- [Functions](#functions){{if ne .PackageName "magefiles"}}
+- [Installation](#installation)
+- [Usage](#usage)
+- [Tests](#tests){{end}}
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Functions
+{{range .Functions}}
+### {{if .StructName}}{{.StructName}}{{end}}{{.Name}}{{if .Params}}({{.Params}}){{end}}
+
+```go
+{{.Signature}}
+```
+
+{{.Description}}
+---
+{{end}}{{if ne .PackageName "magefiles"}}
+## Installation
+
+To use the caldera-security-tests/{{.PackageName}} package, you first need to install it.
+Follow the steps below to install via go get.
+
+```bash
+go get {{.GoGetPath}}
+```
+
+---
+
+## Usage
+
+After installation, you can import the package in your Go project
+using the following import statement:
+
+```go
+import "{{.GoGetPath}}"
+```
+
+---
+
+## Tests
+
+To ensure the package is working correctly, run the following
+command to execute the tests for `caldera-security-tests/{{.PackageName}}`:
+
+```bash
+go test -v
+```
+
+---
+{{end}}
+## Contributing
+
+Pull requests are welcome. For major changes,
+please open an issue first to discuss what
+you would like to change.
+
+---
+
+## License
+
+This project is licensed under the MIT
+License - see the [LICENSE](../LICENSE)
+file for details.