Execute Lua hooks using the HsLua embedded interpreter

Author: ad-si

docs-source/cli/hooks/examples.md

@@ -276,6 +276,42 @@ fn main() {
 ```
 
 
+## Lua Scripts
+
+Save the examples in the hooks directory as `post-add.lua`, etc.
+Lua is the recommended language because TaskLite includes an embedded
+Lua interpreter with the `tl` namespace for utilities like JSON parsing.
+
+
+### Post Add
+
+This example automatically adds a `music` tag when a task has the `jazz` tag:
+
+```lua
+stdin = io.read("*all")
+data = tl.json.decode(stdin)
+
+if data.taskAdded.tags == tl.json.null then
+  return
+end
+
+for _, tag in ipairs(data.taskAdded.tags) do
+  if tag == "jazz" then
+    local handle = io.popen(
+      "tasklite tag music " .. data.taskAdded.ulid,
+      "r"
+    )
+    if handle then
+      handle:read("*a")
+      handle:close()
+    end
+    print(tl.json.encode({message = "Added music tag"}))
+    return
+  end
+end
+```
+
+
 ## Shell Scripts
 
 Save the examples in the hooks directory as `pre-launch.sh`, etc.

docs-source/cli/hooks/main.md

@@ -17,18 +17,47 @@ Otherwise, the file will be executed as a shell script.
 
 Currently supported interpreters are:
 `lua`, `python3`, `ruby`, `node`, and [`v`][vlang].
-It's recommended to write you scripts in the [V programming language][vlang]
-due to its high performance (script is compiled on first execution),
-its great ergonomics, and its comprehensive standard library.
-The compiled versions of the script will be cached as
-`_v_executable_.<name-of-script>` in the hooks directory.
-?
+
 [vlang]: https://vlang.io
 
-Another good alternative is [Lua](https://www.lua.org/)
-as it is simple, lightweight, and fast.
-Furthermore, future versions of TaskLite will include the Lua interpreter
-to make it independent of the system's installed Lua interpreter.
+**Lua is the recommended language** for writing hooks because TaskLite
+includes an embedded Lua interpreter, making hooks portable and independent
+of system installations. Lua hooks also have access to the `tl` namespace
+which provides useful utilities (see below).
+
+Alternatively, you can use the [V programming language][vlang]
+for high performance (scripts are compiled on first execution).
+The compiled versions will be cached as
+`_v_executable_.<name-of-script>` in the hooks directory.
+
+
+## The `tl` Namespace (Lua Only)
+
+Lua hooks have access to a global `tl` namespace that provides
+TaskLite-specific utilities. Currently available:
+
+
+### `tl.json`
+
+A JSON encoding/decoding module:
+
+- `tl.json.decode(string)` - Parse a JSON string into a Lua table
+- `tl.json.encode(table)` - Convert a Lua table to a JSON string
+- `tl.json.null` - A value representing JSON null (for comparisons)
+
+Example:
+
+```lua
+stdin = io.read("*all")
+data = tl.json.decode(stdin)
+
+if data.taskAdded.tags == tl.json.null then
+  return
+end
+
+-- Process the task...
+print(tl.json.encode({message = "Hook completed"}))
+```
 
 If the hook files are shell scripts, they must be executable (`chmod +x`).
 Otherwise, they can't be executed directly by TaskLite.

tasklite-core/package.yaml

@@ -59,6 +59,8 @@ library:
     - ansi-terminal >= 0.11 && < 1.2
     - bytestring >= 0.11 && < 0.13
     - cassava >= 0.5.2 && < 0.6
+    - hslua >= 2.3 && < 2.4
+    - hslua-aeson >= 2.3 && < 2.4
     - containers >= 0.6 && < 0.8
     - colour >= 2.3 && < 2.4
     - directory >= 1.3 && < 1.4

tasklite-core/source/Hooks.hs

@@ -18,8 +18,10 @@ import Protolude qualified as P
 
 import Control.Arrow ((>>>))
 import Data.Aeson qualified as Aeson
+import Data.ByteString.Lazy qualified as BL
 import Data.Text (Text)
 import Data.Text qualified as T
+import Data.Text.Encoding qualified as TE
 import Options.Applicative.Arrows (left)
 import Prettyprinter (Doc, annotate, pretty)
 import Prettyprinter.Render.Terminal (AnsiStyle, Color (Red, Yellow))
@@ -28,6 +30,7 @@ import System.Process (readProcess)
 
 import Config (Config, Hook (body, filePath, interpreter))
 import ImportTask (ImportTask)
+import LuaRunner (runLuaHook)
 import Utils (colr, (<!!>))
 
 
@@ -91,8 +94,6 @@ executeHooks stdinText hooks = do
       if
         | s `P.elem` ["javascript", "js", "node", "node.js"] ->
             ("node", ["-e"], ExecStdin)
-        | s `P.elem` ["lua"] ->
-            ("lua", ["-e"], ExecStdin)
         | s `P.elem` ["python", "python3", "py"] ->
             ("python3", ["-c"], ExecStdin)
         | s `P.elem` ["ruby", "rb"] ->
@@ -103,6 +104,24 @@ executeHooks stdinText hooks = do
         | otherwise ->
             ("", [""], ExecFile)
 
+    -- Execute a Lua hook using the embedded interpreter
+    runEmbeddedLua :: Text -> IO String
+    runEmbeddedLua luaCode = do
+      result <- runLuaHook luaCode stdinText
+      case result of
+        P.Right output -> pure $ T.unpack output
+        P.Left err ->
+          pure $
+            T.unpack $
+              TE.decodeUtf8 $
+                BL.toStrict $
+                  Aeson.encode $
+                    Aeson.object ["error" Aeson..= err]
+
+    -- Check if a file extension or interpreter name indicates Lua
+    isLua :: String -> P.Bool
+    isLua s = s `P.elem` ["lua"]
+
   hookToResult <-
     P.sequence $
       hooks <&> \hook -> do
@@ -112,29 +131,38 @@ executeHooks stdinText hooks = do
               "" ->
                 -- Is executed with shell
                 readProcess fPath [] stdinStr
-              ext -> do
-                let (interpreter, cliFlags, execMode) = getInterpreter ext
-                case execMode of
-                  ExecStdin -> do
+              ext
+                -- Use embedded Lua interpreter for .lua files
+                | isLua ext -> do
                     fileContent <- P.readFile fPath
-                    readProcess
-                      interpreter
-                      (P.concat [cliFlags, [T.unpack fileContent]])
-                      stdinStr
-                  ExecFile -> do
-                    readProcess
-                      interpreter
-                      (P.concat [cliFlags, [fPath]])
-                      stdinStr
+                    runEmbeddedLua fileContent
+                | otherwise -> do
+                    let (interpreterCmd, cliFlags, execMode) = getInterpreter ext
+                    case execMode of
+                      ExecStdin -> do
+                        fileContent <- P.readFile fPath
+                        readProcess
+                          interpreterCmd
+                          (P.concat [cliFlags, [T.unpack fileContent]])
+                          stdinStr
+                      ExecFile -> do
+                        readProcess
+                          interpreterCmd
+                          (P.concat [cliFlags, [fPath]])
+                          stdinStr
           ---
           Nothing -> do
-            let
-              (interpreter, cliFlags, _) =
-                getInterpreter (T.unpack hook.interpreter)
-            readProcess
-              interpreter
-              (P.concat [cliFlags, [T.unpack hook.body]])
-              stdinStr
+            -- Use embedded Lua interpreter for inline Lua hooks
+            if isLua (T.unpack hook.interpreter)
+              then runEmbeddedLua hook.body
+              else do
+                let
+                  (interpreterCmd, cliFlags, _) =
+                    getInterpreter (T.unpack hook.interpreter)
+                readProcess
+                  interpreterCmd
+                  (P.concat [cliFlags, [T.unpack hook.body]])
+                  stdinStr
 
   let parsedHookResults :: [P.Either Text HookResult] =
         hookToResult