Add runtime GNU-tool guard; document Linux-only platform support

shuriken shells out to GNU-only features of the standard Unix tools
(find -printf, stat -c, cp -a, sort -R). Add require_gnu_tools in a new
src/lib/compat.source.sh, sourced early and invoked from main() before any
action runs. On invocation it feature-probes each tool in a throwaway temp
dir; if any probe fails it prints a clear error naming the offending tool
and exits 1, so non-GNU (macOS/BSD) environments fail fast instead of
producing broken output.

README gains a Platform compatibility section and the requirements line now
mentions GNU coreutils/findutils. Tests cover the find and stat rejection
paths; the shared test helper that builds a coreutils-without-imagemagick
PATH now includes cp and stat (which the guard probes).

2 files changed, 81 insertions, 0 deletions

diff --git a/tests/cli.sh b/tests/cli.sh
index e3af898..3ce8939 100755
--- a/tests/cli.sh
+++ b/tests/cli.sh
@@ -6190,6 +6190,79 @@ test_empty_args_fail() {
     test::assert_contains 'Usage:' "$output"
 }
 
+# The runtime GNU-tool guard (require_gnu_tools in src/lib/compat.source.sh)
+# must reject invocations when a core tool lacks the GNU-only feature shuriken
+# depends on. Each case installs a complete coreutils set via the shared
+# helper (so the environment is otherwise real), then replaces exactly one tool
+# with a fake that mimics the BSD/macOS behavior (rejecting the GNU flag), runs a
+# valid action, and asserts a clear GNU-only error. The guard runs before any
+# action work, so even --version is gated.
+test_gnu_tool_guard_rejects_non_gnu_find() {
+    local path_bin
+    local real_find
+    local output
+
+    test::setup
+    path_bin="$TEST_TMPDIR/bin"
+    real_find=$(command -v find)
+    test::install_coreutils_without_imagemagick "$path_bin"
+    rm -f "$path_bin/find"
+    cat > "$path_bin/find" <<FAKE
+#!/usr/bin/env bash
+set -euo pipefail
+for arg in "\$@"; do
+    if [ "\$arg" = -printf ]; then
+        printf 'find: unknown predicate -printf\n' >&2
+        exit 2
+    fi
+done
+exec "$real_find" "\$@"
+FAKE
+    chmod 0755 "$path_bin/find"
+
+    output=$(
+        cd "$TEST_TMPDIR"
+        PATH="$path_bin" test::capture_failure_output \
+            "$TEST_SHURIKEN" --version
+    )
+
+    test::assert_contains 'shuriken requires the GNU versions' "$output"
+    test::assert_contains 'find (missing the -printf action)' "$output"
+    test::teardown
+}
+
+test_gnu_tool_guard_rejects_non_gnu_stat() {
+    local path_bin
+    local real_stat
+    local output
+
+    test::setup
+    path_bin="$TEST_TMPDIR/bin"
+    real_stat=$(command -v stat)
+    test::install_coreutils_without_imagemagick "$path_bin"
+    rm -f "$path_bin/stat"
+    cat > "$path_bin/stat" <<FAKE
+#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = -c ]; then
+    printf 'stat: illegal option -c\n' >&2
+    exit 1
+fi
+exec "$real_stat" "\$@"
+FAKE
+    chmod 0755 "$path_bin/stat"
+
+    output=$(
+        cd "$TEST_TMPDIR"
+        PATH="$path_bin" test::capture_failure_output \
+            "$TEST_SHURIKEN" --version
+    )
+
+    test::assert_contains 'shuriken requires the GNU versions' "$output"
+    test::assert_contains 'stat (missing the -c option)' "$output"
+    test::teardown
+}
+
 test_extra_args_fail() {
     test::assert_failure 'extra operand is rejected' "$TEST_SHURIKEN" --version extra
     test::assert_failure \
@@ -7040,6 +7113,12 @@ main() {
     test::run_case 'empty args fail' test_empty_args_fail
     test::run_case 'extra args fail' test_extra_args_fail
     test::run_case 'missing option values fail' test_missing_option_values_fail
+    test::run_case \
+        'GNU-tool guard rejects non-GNU find' \
+        test_gnu_tool_guard_rejects_non_gnu_find
+    test::run_case \
+        'GNU-tool guard rejects non-GNU stat' \
+        test_gnu_tool_guard_rejects_non_gnu_stat
 }
 
 main "$@"
diff --git a/tests/helpers.sh b/tests/helpers.sh
index d258c79..e377737 100755
--- a/tests/helpers.sh
+++ b/tests/helpers.sh
@@ -695,6 +695,7 @@ test::install_coreutils_without_imagemagick() {
     local -a names=(
         basename
         bash
+        cp
         date
         dirname
         find
@@ -704,6 +705,7 @@ test::install_coreutils_without_imagemagick() {
         rm
         sed
         sort
+        stat
         tac
         tar
         wc