From 88cec5db4662a5a3ad6119e988dd93adf1596af0 Mon Sep 17 00:00:00 2001
From: Robert Morrison <robert@closedless.xyz>
Date: Fri, 10 Apr 2026 02:15:36 +0100
Subject: [PATCH] feat(utils): Add scriptutils

Currently only has one util, but this may grow
---
 lua/sherlock5512/scriptutils/init.lua  | 33 ++++++++++++++++++++++++++
 lua/sherlock5512/scriptutils/types.lua |  4 ++++
 2 files changed, 37 insertions(+)
 create mode 100644 lua/sherlock5512/scriptutils/init.lua
 create mode 100644 lua/sherlock5512/scriptutils/types.lua

diff --git a/lua/sherlock5512/scriptutils/init.lua b/lua/sherlock5512/scriptutils/init.lua
new file mode 100644
index 0000000..7b964ed
--- /dev/null
+++ b/lua/sherlock5512/scriptutils/init.lua
@@ -0,0 +1,33 @@
+-- scriptutils: some useful functions for scripts to use.
+
+require('sherlock5512.scriptutils.types')
+
+local M = {}
+
+
+--- Run a command in a shell
+-- This function only works on UNIX-like systems 
+-- that have a POSIX compliant shell installed.
+---@param cmdline string Your command-line to send to sh
+---@param timeout? integer Timeout for command
+---@return shReturn status [1]
+---@return string? stdout the contents of stdout from executing your cmdline
+function M.shellexec(cmdline,timeout)
+	timeout = timeout or nil
+	-- by default vim.system runs async, but as we need the output immediately we don't really need that.
+	-- Note the timeout is passed to wait and not as an option to system,
+	-- In this case I don't think it really matters as we wait immediately after calling vim.system
+	local result = vim.system({'sh', '-c', cmdline}):wait(timeout)
+	-- Breaking the result into variables makes my programming intent clearer
+	local stdout = result.stdout
+	local stderr = result.stderr
+	local code = result.code
+
+	return {
+		ok = (code == 0),
+		code = code,
+		stderr = stderr,
+	}, stdout
+end
+
+return M
diff --git a/lua/sherlock5512/scriptutils/types.lua b/lua/sherlock5512/scriptutils/types.lua
new file mode 100644
index 0000000..91313ee
--- /dev/null
+++ b/lua/sherlock5512/scriptutils/types.lua
@@ -0,0 +1,4 @@
+---@class shReturn
+---@field ok boolean True if successful
+---@field code integer Return code (useful for debugging)
+---@field stderr string Stderr (if any)