docs: documented the now built-in bash helper script and the tools it comes with

docs/function-calling/BASH-PROMPT-HELPERS.md

@@ -0,0 +1,275 @@
+# Bash Prompt Helpers
+
+When creating bash based tools, it's often helpful to prompt the user for input or confirmation.
+
+Loki comes pre-packaged with a handful of prompt helpers for your bash-based tools. These helpers
+can be used to prompt the user for various types of input, such as yes/no confirmations,
+text input, and selections from a list.
+
+The utility script is located at `functions/utils/prompt-utils.sh` within your Loki `functions` directory.
+
+The Loki `functions` directory varies between machines, so you can find its location on your system by running the following command in your terminal:
+
+```shell
+loki --info | grep functions_dir | awk '{print $2}'
+```
+
+## Quick Links
+<!--toc:start-->
+- [Import The Prompt Utils Into Your Tools Script](#import-the-prompt-utils-into-your-tools-script)
+- [Included Utility Functions](#included-utility-functions)
+  - [input](#input)
+  - [confirm](#confirm)
+  - [list](#list)
+  - [checkbox](#checkbox)
+  - [password](#password)
+  - [editor](#editor)
+  - [with_validate](#with_validate)
+  - [validate_present](#validate_present)
+  - [detect_os](#detect_os)
+  - [get_opener](#get_opener)
+  - [open_link](#open_link)
+  - [guard_operation](#guard_operation)
+  - [guard_path](#guard_path)
+  - [patch_file](#patch_file)
+  - [error](#error)
+  - [warn](#warn)
+  - [info](#info)
+  - [debug](#debug)
+  - [trace](#trace)
+  - [Colored Output](#colored-output)
+<!--toc:end-->
+
+---
+
+## Import The Prompt Utils Into Your Tools Script
+In order to use the bash prompt helpers in your bash scripts, you need to source the provided `prompt-utils.sh` script.
+This script is pre-packaged with Loki and is located [here](../../assets/functions/utils/prompt-utils.sh).
+
+When sourcing the file in your bash script, you use the `LLM_PROMPT_UTILS_FILE` environment variable that automatically 
+populates the `functions/utils/prompt-utils.sh` path for you.
+
+Thus, to properly source and enable all the bash prompt helpers in your Bash tools, add the following prelude to your
+scripts:
+
+```bash
+source "$LLM_PROMPT_UTILS_FILE"
+```
+
+## Included Utility Functions
+Below are the built-in bash prompt helpers that can be used to enhance user interaction with your tool scripts.
+
+### input
+Prompt for text input
+
+![Prompt Utils Input](../images/tools/prompt-utils-input.png)
+
+**Example With Validation:**
+```bash
+text=$(with_validation 'input "Please enter something:"' validate_present)
+```
+
+**Example Without Validation:**
+```bash
+text=$(input "Please enter something:")
+```
+
+### confirm
+Show a confirm dialog with options for yes/no
+
+![Prompt Utils Confirm](../images/tools/prompt-utils-confirm.png)
+
+**Example:**
+```bash
+confirmed=$(confirm "Do the thing?")
+if [[ $confirmed == "0" ]]; then echo "No"; else echo "Yes"; fi
+```
+
+### list
+Renders a text based list of options that can be selected by the user using up, down, and enter
+keys that then returns the chosen option.
+
+![Prompt Utils List](../images/tools/prompt-utils-list.png)
+
+**Example:**
+```bash
+options=("one" "two" "three" "four")
+choice=$(list "Select an item" "${options[@]}")
+echo "Your choice: ${options[$choice]}"
+```
+
+### checkbox
+Render a text based list of options, where multiple options can be selected by the user using down, up,
+and enter keys that then returns the chosen options.
+
+![Prompt Utils Checkbox](../images/tools/prompt-utils-checkbox.png)
+
+**Example:**
+```bash
+options=("one" "two" "three" "four")
+checked=$(checkbox "Select one or more items" "${options[@]}")
+echo "Your choices: ${checked}"
+```
+
+### password
+Show a password prompt displaying stars for each character typed.
+
+![Prompt Utils Password](../images/tools/prompt-utils-password.png)
+
+**Example With Validation:**
+```bash
+validate_password() {
+  if [[ ${#1} -lt 10 ]]; then
+    echo "Password must be at least 10 characters"
+    exit 1
+  fi
+}
+pass=$(with_validate 'password "Enter your password"' validate_password)
+```
+
+**Example Without Validation:**
+```bash
+pass="$(password "Enter your password:")"
+```
+
+### editor
+Open the default editor (`$EDITOR`); if none is set, default back to `vi`
+
+**Example:**
+```bash
+text=$(editor "Please enter something in the editor")
+echo -e "You wrote:\n${text}"
+```
+
+### with_validate
+Evaluate the given prompt command with validation. This prompts the user for input until the
+validation functions returns 0.
+
+![Prompt Utils With-validate](../images/tools/prompt-utils-with-validate.png)
+
+**Example:**
+```bash
+# Using the built-in 'validate_present' validator
+text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present)
+
+# Using a custom validator; e.g. for password
+validate_password() {
+  if [[ ${#1} -lt 10 ]]; then
+    echo "Password needs to be at least 10 characters"
+    exit 1
+  fi
+}
+pass=$(with_validate 'password "Enter random password"' validate_password)
+```
+
+### validate_present
+Validate that the prompt returned a value.
+
+![Prompt Utils Validate-Present](../images/tools/prompt-utils-validate-present.png)
+
+**Example:**
+```bash
+text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present)
+```
+
+### detect_os
+Detect the current OS.
+
+Returns one of the following:
+
+* `solaris`
+* `macos`
+* `linux`
+* `bsd`
+* `windows`
+* `unknown`
+
+**Example:**
+```bash
+detect_os
+```
+
+### get_opener
+Determines the Os-specific file opening command (i.e. the command to open anything)
+
+**Example:**
+```bash
+# Returns 'xdg-open'
+get_opener
+```
+
+### open_link
+Opens the given link in the default browser
+
+**Example:**
+```bash
+open_link https://www.google.com
+```
+
+### guard_operation
+Prompt for permission to run an operation
+
+**Example:**
+```bash
+guard_operation "Execute SQL?"
+_run_sql
+```
+
+### guard_path
+Prompt for permission to perform path operations
+
+**Example:***
+```bash
+guard_path "$target_path" "Remove '$target_path'?"
+rm -rf "$target_path"
+```
+
+### patch_file
+Patch a file and show a diff using the default diff viewer. Uses git diff syntax.
+
+**Example:**
+```bash
+new_contents="$(patch_file "$path" file.patch)"
+```
+
+### error
+Log an error
+
+![Prompt Utils Error](../images/tools/prompt-utils-error.png)
+
+### warn
+Log a warning
+
+![Prompt Utils Warning](../images/tools/prompt-utils-warning.png)
+
+### info
+Log info
+
+![Prompt Utils Info](../images/tools/prompt-utils-info.png)
+
+### debug
+Log a debug message
+
+![Prompt Utils Debug](../images/tools/prompt-utils-debug.png)
+
+### trace
+Log a trace message
+
+![Prompt Utils Trace](../images/tools/prompt-utils-trace.png)
+
+### Colored Output
+The following commands allow users to output text in specific colors.
+
+* `red`
+* `green`
+* `gold`
+* `blue`
+* `magenta`
+* `cyan`
+* `white`
+
+**Example:**
+```bash
+red "This will be red"
+yellow "This will be yellow"
+```