tools: add fzf wrapping script

introduce iretis.sh (interactive retis) that essentially performs some
minor checks and make retis fzf and bat play nice together.

Signed-off-by: Paolo Valerio <pvalerio@redhat.com>

Author: vlrpl

docs/index.md

@@ -269,3 +269,28 @@ Output can then be piped through bat directly:
 $ retis print retis.data | bat --language retis
 ```
 
+## Interactive filtering with fzf
+
+[`iretis.sh`](https://raw.githubusercontent.com/retis-org/retis/main/tools/iretis.sh)
+wraps `retis` and pipes the output into [fzf](https://github.com/junegunn/fzf)
+for interactive multi-event browsing and filtering. Set `COLORS=1` to enable
+syntax highlighting via [bat](https://github.com/sharkdp/bat) at the same time:
+
+```none
+$ COLORS=1 iretis.sh collect ...
+$ COLORS=1 iretis.sh sort retis.data
+$ COLORS=1 iretis.sh print retis.data
+```
+
+`RETIS_BIN` can be set to point to a specific retis binary (default: `retis`
+from `PATH`), which is useful when running a locally built binary or with
+[`retis_in_container.sh`](https://raw.githubusercontent.com/retis-org/retis/main/tools/retis_in_container.sh).
+
+`ERR_LOG` can be set to a file path where retis stderr is captured and printed
+after fzf exits, keeping the fzf interface uncluttered. If set, stderr is also
+saved to the specified file:
+
+```none
+$ ERR_LOG=/tmp/retis-err.log iretis.sh collect ...
+```
+

tools/iretis.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# iretis: run retis and interactively browse events with fzf.
+#
+# Usage: iretis.sh <collect|sort|print> [retis args...]
+#
+# Environment variables:
+#   RETIS_BIN      path to the retis binary (default: retis from PATH)
+#   COLORS         set to 1 to pipe output through bat for syntax highlighting
+#   ERR_LOG        path to a file where retis stderr is saved in addition to
+#                  being printed after fzf exits (default: not set)
+#
+# Note:
+#   If you built bat cache on custom locations (e.g. you run collect with
+#   sudo and your profile was built in the user's homedir) use
+#   BAT_CACHE_PATH=$HOME/.cache/bat
+#   Use BAT_THEME=<theme> to use a non-default color scheme.
+
+set -e
+
+RETIS_BIN=$(command -v "${RETIS_BIN:-retis}") \
+    || { echo "Error: retis not found in PATH or RETIS_BIN"; exit 2; }
+
+_ERR_TMP=$(mktemp)
+
+cleanup() {
+    [[ -s "$_ERR_TMP" ]] && cat "$_ERR_TMP" >&2
+    [[ -n "$ERR_LOG" ]] && mv "$_ERR_TMP" "$ERR_LOG" || rm -f "$_ERR_TMP"
+}
+trap cleanup EXIT
+
+command -v fzf >/dev/null 2>&1 \
+    || { echo "Error: fzf not found in PATH"; exit 2; }
+
+if [[ "${COLORS:-0}" -eq 1 ]]; then
+    command -v bat >/dev/null 2>&1 \
+        || { echo "Error: bat not found in PATH (required for COLORS=1)"; exit 2; }
+fi
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: iretis.sh <collect|sort|print> [retis args...]"
+    exit 2
+fi
+
+_SUBCMD=""
+for arg in "$@"; do
+    case "$arg" in
+        collect|sort|print)
+            _SUBCMD="$arg"
+            break
+            ;;
+    esac
+done
+
+if [[ -z "$_SUBCMD" ]]; then
+    echo "Error: one of collect, sort or print must be provided in the extended format"
+    exit 2
+fi
+
+fzf_cmd="fzf --read0 --multi-line --ansi --no-sort --tac"
+
+if [[ "${COLORS:-0}" -eq 1 ]]; then
+    "$RETIS_BIN" "$@" 2> $_ERR_TMP \
+        | bat --language retis --color always --paging never -pp \
+        | awk 'BEGIN{RS=""; ORS="\0"} {print; fflush()}' \
+        | $fzf_cmd
+else
+    "$RETIS_BIN" "$@" 2> $_ERR_TMP \
+        | awk 'BEGIN{RS=""; ORS="\0"} {print; fflush()}' \
+        | $fzf_cmd
+fi