Merge pull request 'feat: XDG Base Directory compliance, --uninstall flag, and xclip advisory' (#13) from feat/xdg-compliance-and-uninstall into main

Reviewed-on: #13

.gitea/workflows/label-pr.yaml

@@ -0,0 +1,42 @@
+name: Auto Label PRs
+
+on:
+  pull_request:
+    types: [opened, edited]
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Apply labels based on PR title
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO_OWNER: ${{ github.repository_owner }}
+          REPO_NAME: ${{ github.event.repository.name }}
+          API_URL: ${{ github.api_url }}
+        run: |
+          shopt -s nocasematch
+          
+          labels="["
+          
+          if [[ "$PR_TITLE" =~ ^(ci|test)(/|:) ]]; then
+            labels="${labels}13," # 13 is Kind/Testing
+          fi
+          
+          if [[ "$PR_TITLE" =~ ^docs(/|:) ]]; then
+            labels="${labels}14," # 14 is Kind/Documentation
+          fi
+          
+          labels="${labels%,}]"
+          
+          if [ "$labels" != "[]" ]; then
+            echo "Adding labels to PR #${PR_NUMBER}: ${labels}"
+            curl -X POST "${API_URL}/repos/${REPO_OWNER}/${REPO_NAME}/issues/${PR_NUMBER}/labels" \
+              -H "Authorization: token ${GITHUB_TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "{\"labels\": ${labels}}"
+          else
+            echo "No matching prefixes found in title: ${PR_TITLE}"
+          fi

.gitea/workflows/release.yaml

@@ -8,7 +8,10 @@ on:
 
 jobs:
   release:
-    if: github.event.pull_request.merged == true
+    if: |
+      github.event.pull_request.merged == true &&
+      !contains(github.event.pull_request.labels.*.name, 'Kind/Testing') &&
+      !contains(github.event.pull_request.labels.*.name, 'Kind/Documentation')
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code

.gitea/workflows/test.yaml

@@ -0,0 +1,22 @@
+name: Test PR
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    if: "!contains(github.event.pull_request.labels.*.name, 'Kind/Documentation')"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Make scripts executable
+        run: |
+          chmod +x color-tool
+          chmod +x tests/run_tests.sh
+
+      - name: Run test suite
+        run: ./tests/run_tests.sh

README.md

@@ -10,33 +10,62 @@ A feature-rich, portable CLI color utility for Linux, specializing in color pick
 - **Smart JSON Output:** Generate machine-readable JSON tables for easy integration with other tools.
 - **Color Naming:** Resolve hex values to human-readable names via thecolorapi.com.
 - **Visual Previews:** Render color swatches directly in your terminal using truecolor ANSI escapes.
-- **Desktop Integration:** Built-in support for clipboard copying (`wl-copy`/`xclip`) and desktop notifications.
+- **Desktop Integration:** Built-in support for clipboard copying (`wl-copy`/`xclip`) and rich desktop notifications with visual color swatches.
 - **Highly Configurable:** Separate configuration profiles for standard terminal usage and desktop/launcher mode.
 - **Portable Design:** The entire tool is contained within a single Bash script, with embedded Python helpers.
 
 ## 📋 Prerequisites
 
-To utilize all features, ensure the following are installed:
-- **KDE Plasma + Wayland:** Required for the `--pick` functionality.
-- **Python 3 + PyQt6:** Required for the picker helper.
-- **curl + jq:** Required for color naming support.
-- **wl-clipboard** (Wayland) or **xclip** (X11): Required for clipboard support.
-- **libnotify:** Required for desktop notifications (`notify-send`).
+### Required Core Dependencies
+These are mandatory for the script to run and perform basic color conversions:
+- **Python 3:** Handles all color space math and conversions.
+- **jq:** Powers JSON formatting and internal data parsing.
+
+### Optional Feature Dependencies
+These enable specific functionality and can be installed as needed:
+- **KDE Plasma (Wayland):** Required for screen color picking (`--pick`).
+- **Python 3 PyQt6:** Required for the KDE color picker DBus interface.
+- **wl-clipboard** or **xclip:** Enables copying results to the system clipboard (`--copy`). `wl-clipboard` is strongly preferred on Wayland — `xclip` operates through XWayland and can be unreliable. `--check-deps` and `--install` will warn you if only `xclip` is found.
+- **curl:** Required for fetching human-readable color names from the web (`--name`).
+- **libnotify:** Enables desktop notifications (`--notify`).
+- **ImageMagick:** Generates visual color swatch icons for notifications (`--swatch`).
+- **Truecolor Terminal Emulator:** Required for accurate visual swatches in terminal output (`--swatch`).
+
+> **Tip:** Use `color-tool --check-deps` to quickly see which dependencies are currently met on your system.
 
 ## 🚀 Installation
 
-Simply download the `color-tool` script and run the install command:
+### Automatic Installation (Recommended)
+
+You can download the script directly from the [latest release](https://git.rootiest.dev/rootiest/color-tool/releases/latest) and install it:
 
 ```bash
-chmod +x color-tool
-./color-tool --install
+# Download and install the latest version of the color-tool script
+curl -sSLO https://git.rootiest.dev/rootiest/color-tool/releases/download/latest/color-tool && bash color-tool --install && rm ./color-tool
 ```
 
 This will:
-1. Move the script to `~/.local/share/color-tool/`.
+1. Install the script to `$XDG_DATA_HOME/color-tool/` (default: `~/.local/share/color-tool/`).
 2. Symlink the binary to `~/.local/bin/color-tool`.
-3. Generate a sample configuration at `~/.config/color-tool/config.toml`.
-4. Create a `.desktop` entry so you can launch the picker from your application menu.
+3. Generate a sample configuration at `$XDG_CONFIG_HOME/color-tool/config.toml` (default: `~/.config/color-tool/config.toml`).
+4. Create a `.desktop` entry in `$XDG_DATA_HOME/applications/` so you can launch the picker from your application menu.
+5. Verify and warn about any missing optional or required system dependencies.
+6. Clean up the downloaded script after installation.
+
+### Manual Usage
+
+Alternatively, you can [download the script](https://git.rootiest.dev/rootiest/color-tool/releases/download/latest/color-tool) manually.
+Then run it from any location without installation:
+
+```bash
+# Make script executable
+chmod +x color-tool
+# Run script directly
+./color-tool --pick --output hex,rgb
+```
+
+However, this will not add the script to your `$PATH` or create a desktop entry,
+so you won't be able to launch it from the app menu or use it globally without specifying the path.
 
 ## 🛠 Usage
 
@@ -52,7 +81,11 @@ Options:
   --[no-]copy    Copy result to clipboard
   --[no-]notify  Show desktop notification
   --desktop      GUI mode: pick → copy → notify
-  --install      Install to ~/.local/share/ and symlink to ~/.local/bin/
+  --get-config   Print the current configuration
+  --set-config   Update the configuration (e.g. --set-config desktop --copy)
+  --reset-config Restore the configuration file to its default values
+  --check-deps   Check system dependencies and environment support
+  --install      Install to $XDG_DATA_HOME/color-tool/ and symlink to ~/.local/bin/
   --help, -h     Show this help message
 ```
 
@@ -80,26 +113,57 @@ color-tool --desktop --no-name
 
 ## ⚙️ Configuration
 
-You can define your preferred defaults in `~/.config/color-tool/config.toml`. The tool uses a priority hierarchy: **CLI Flags > Desktop Config > Default Config**.
+You can define your preferred defaults in `$XDG_CONFIG_HOME/color-tool/config.toml` (default: `~/.config/color-tool/config.toml`). The tool uses a priority hierarchy: **CLI Flags > Desktop Config > Default Config**.
 
 ```toml
 [defaults]
-output = "hex"  # default output format(s)
+# Set any option to true to enable it by default when using the terminal
+output = "hex"  # default output format(s): hex, rgb, hsl, rgba, hsla, hexa, all
 json   = false  # output in JSON format
 swatch = false  # show color swatch in terminal
-name   = false  # fetch color name
+name   = false  # fetch color name from thecolorapi.com
 copy   = false  # copy result to clipboard
-pick   = false  # auto-launch picker
+pick   = false  # auto-launch color picker when invoked with no arguments
 notify = false  # show desktop notification
 
 [desktop]
-output = "hex"
-json   = false
-name   = false
-copy   = true
-notify = true
+# Defaults for --desktop mode (launched from the app menu; copy is always enabled by default)
+output = "hex"  # format to copy
+json   = false  # copy JSON format instead of plain text
+name   = false  # fetch color name (requires network)
+copy   = true   # copy result to clipboard
+notify = true   # show desktop notification with the copied value
+swatch = true   # show color swatch in notification
 ```
 
+You can also use the CLI to manage your configuration:
+
+```bash
+# View current config
+color-tool --get-config
+
+# Update specific keys (e.g., enable swatch by default)
+color-tool --set-config defaults --swatch
+
+# Set output format for desktop mode
+color-tool --set-config desktop output=rgba
+
+# Reset to factory defaults
+color-tool --reset-config
+```
+
+## 🧪 Testing
+
+The project includes a comprehensive test suite that verifies color conversion, configuration loading, and system integrations (clipboard/notifications) using mocks.
+
+To run the tests:
+
+```bash
+./tests/run_tests.sh
+```
+
+The test script creates a temporary isolated environment, so it won't affect your system configuration or active clipboard.
+
 ## 🤝 Credits
 
 The `wl-colorpicker-plasma` integration is based on the original work by [SASUPERNOVA](https://github.com/SASUPERNOVA/wl-colorpicker-plasma).

tests/run_tests.sh

@@ -0,0 +1,284 @@
+#!/bin/bash
+set -euo pipefail
+
+# ── Setup ─────────────────────────────────────────────────────────────────────
+# Using a static-ish path since we can't use command substitution in cat
+TEST_DIR="/tmp/color-tool-tests-repro"
+BIN_DIR="$TEST_DIR/bin"
+rm -rf "$TEST_DIR"
+mkdir -p "$BIN_DIR"
+
+# Mock notify-send
+cat <<'MOCK' > "$BIN_DIR/notify-send"
+#!/bin/bash
+echo "NOTIFY: $*" >> "/tmp/color-tool-tests-repro/notify.log"
+MOCK
+
+# Mock wl-copy
+cat <<'MOCK' > "$BIN_DIR/wl-copy"
+#!/bin/bash
+cat > "/tmp/color-tool-tests-repro/clipboard.txt"
+MOCK
+
+# Mock python3
+cat <<'MOCK' > "$BIN_DIR/python3"
+#!/bin/bash
+if [[ "$*" == *wl-colorpicker*.py ]]; then
+  echo "#aabbcc"
+  exit 0
+fi
+exec /usr/bin/python3 "$@"
+MOCK
+
+chmod +x "$BIN_DIR"/*
+
+# Symlink essential tools
+ln -s /usr/bin/bash "$BIN_DIR/bash"
+ln -s /usr/bin/cat "$BIN_DIR/cat"
+ln -s /usr/bin/printf "$BIN_DIR/printf"
+ln -s /usr/bin/echo "$BIN_DIR/echo"
+ln -s /usr/bin/sed "$BIN_DIR/sed"
+ln -s /usr/bin/grep "$BIN_DIR/grep"
+ln -s /usr/bin/awk "$BIN_DIR/awk"
+ln -s /usr/bin/jq "$BIN_DIR/jq"
+ln -s /usr/bin/readlink "$BIN_DIR/readlink"
+ln -s /usr/bin/dirname "$BIN_DIR/dirname"
+ln -s /usr/bin/mkdir "$BIN_DIR/mkdir"
+ln -s /usr/bin/mktemp "$BIN_DIR/mktemp"
+ln -s /usr/bin/chmod "$BIN_DIR/chmod"
+ln -s /usr/bin/rm "$BIN_DIR/rm"
+# Mock curl for thecolorapi.com
+cat <<'MOCK' > "$BIN_DIR/curl"
+#!/bin/bash
+if [[ "$*" == *"thecolorapi.com"* ]]; then
+  echo '{"name": {"value": "Mocked Color Name"}}'
+  exit 0
+fi
+exec /usr/bin/curl "$@"
+MOCK
+chmod +x "$BIN_DIR/curl"
+ln -s /usr/bin/mv "$BIN_DIR/mv"
+ln -s /usr/bin/tr "$BIN_DIR/tr"
+ln -s /usr/bin/cp "$BIN_DIR/cp"
+ln -s /usr/bin/ln "$BIN_DIR/ln"
+
+export PATH="$BIN_DIR"
+export HOME="$TEST_DIR"
+export XDG_CONFIG_HOME="$TEST_DIR/.config"
+export XDG_DATA_HOME="$TEST_DIR/.local/share"
+export WAYLAND_DISPLAY=wayland-0
+export XDG_CURRENT_DESKTOP=KDE
+
+# Resolve the absolute path of color-tool
+COLOR_TOOL="$(/usr/bin/readlink -f ./color-tool)"
+
+# ── Test Helpers ──────────────────────────────────────────────────────────────
+total=0
+passed=0
+
+it() {
+  local label="$1"
+  total=$((total + 1))
+  printf "Test: %s... " "$label"
+}
+
+assert_contains() {
+  local haystack="$1"
+  local needle="$2"
+  if [[ "$haystack" == *"$needle"* ]]; then
+    echo "PASS"
+    passed=$((passed + 1))
+  else
+    echo "FAIL"
+    echo "  Expected to find: $needle"
+    echo "  Actual output: $haystack"
+    return 1
+  fi
+}
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+# 1. Basic Conversion
+it "converts hex to rgb"
+output=$("$COLOR_TOOL" "#ffffff" --output rgb --no-copy --no-notify)
+assert_contains "$output" "rgb(255, 255, 255)"
+
+# 2. Multiple Formats
+it "handles multiple formats"
+output=$("$COLOR_TOOL" "#000000" --output hex,rgba --no-copy --no-notify)
+assert_contains "$output" "#000000 rgba(0, 0, 0, 1.0)"
+
+# 3. Clipboard Integration
+it "copies to clipboard (mocked)"
+rm -f "$TEST_DIR/clipboard.txt"
+"$COLOR_TOOL" "#ff0000" --copy --no-notify >/dev/null
+if [[ -f "$TEST_DIR/clipboard.txt" ]]; then
+  assert_contains "$(cat "$TEST_DIR/clipboard.txt")" "#ff0000"
+else
+  echo "FAIL (clipboard.txt not created)"
+fi
+
+# 4. Notification Integration
+it "sends notifications (mocked)"
+rm -f "$TEST_DIR/notify.log"
+"$COLOR_TOOL" "#00ff00" --notify --no-copy >/dev/null
+if [[ -f "$TEST_DIR/notify.log" ]]; then
+  assert_contains "$(cat "$TEST_DIR/notify.log")" "NOTIFY: -i color-picker color-tool #00ff00"
+else
+  echo "FAIL (notify.log not created)"
+fi
+
+# 5. Color Picker (Mocked)
+it "launches color picker and processes result"
+output=$("$COLOR_TOOL" --pick --no-copy --no-notify)
+assert_contains "$output" "#aabbcc"
+
+# 6. Config Loading
+it "loads defaults from config.toml"
+mkdir -p "$HOME/.config/color-tool"
+cat <<'CONF' > "$HOME/.config/color-tool/config.toml"
+[defaults]
+output = "rgba"
+CONF
+output=$("$COLOR_TOOL" "#ffffff" --no-copy --no-notify)
+assert_contains "$output" "rgba(255, 255, 255, 1.0)"
+
+# 7. Error Notification
+it "notifies on missing clipboard utility"
+rm -f "$BIN_DIR/wl-copy"
+rm -f "$TEST_DIR/notify.log"
+"$COLOR_TOOL" "#123456" --copy --notify 2>/dev/null >/dev/null
+if [[ -f "$TEST_DIR/notify.log" ]]; then
+  assert_contains "$(cat "$TEST_DIR/notify.log")" "NOTIFY: -u normal -i dialog-warning color-tool Missing clipboard utility"
+else
+  echo "FAIL (notify.log not created)"
+fi
+
+# 8. Config Management
+it "manages configuration via CLI"
+mkdir -p "$HOME/.config/color-tool"
+"$COLOR_TOOL" --reset-config >/dev/null
+
+# Test --set-config
+"$COLOR_TOOL" --set-config defaults output=rgba
+output=$("$COLOR_TOOL" --get-config)
+if [[ "$output" == *"output = \"rgba\""* ]]; then
+  # Test --reset-config
+  "$COLOR_TOOL" --reset-config >/dev/null
+  output=$("$COLOR_TOOL" --get-config)
+  assert_contains "$output" "output = \"hex\""
+else
+  echo "FAIL"
+  echo "  Expected to find: output = \"rgba\""
+  echo "  Actual output: $output"
+fi
+
+# 9. JSON Output
+it "outputs selected formats as JSON"
+output=$("$COLOR_TOOL" "#00ff00" --output hex,rgb --json --no-copy --no-notify)
+if [[ "$output" == *'"hex": "#00ff00"'* ]] && [[ "$output" == *'"rgb": "rgb(0, 255, 0)"'* ]]; then
+  echo "PASS"
+  passed=$((passed + 1))
+else
+  echo "FAIL"
+  echo "  Actual output: $output"
+fi
+
+# 10. Swatch Output
+it "outputs visual swatch"
+output=$("$COLOR_TOOL" "#112233" --output hex --swatch --no-copy --no-notify)
+if [[ "$output" == *"$(printf "\033[48;2;17;34;51m  \033[0m")"* ]] && [[ "$output" == *"#112233"* ]]; then
+  echo "PASS"
+  passed=$((passed + 1))
+else
+  echo "FAIL"
+  echo "  Actual output: $output"
+fi
+
+# 11. Color Name Fetching
+it "fetches color name from thecolorapi.com"
+output=$("$COLOR_TOOL" "#ffffff" --output hex --name --no-copy --no-notify)
+assert_contains "$output" "(Mocked Color Name)"
+
+# 12. Invalid Color Input
+it "rejects invalid colors"
+output=$("$COLOR_TOOL" "invalid-color" --no-copy --no-notify 2>&1 || true)
+assert_contains "$output" "Error: Invalid color: invalid-color"
+
+# 13. Invalid Format Input
+it "rejects invalid formats"
+output=$("$COLOR_TOOL" "#000000" --output badfmt --no-copy --no-notify 2>&1 || true)
+assert_contains "$output" "Error: Invalid output format: badfmt"
+
+# 14. Installation Dependency Warnings
+it "warns about missing dependencies during install"
+mkdir -p "$TEST_DIR/install_bin"
+for cmd in bash cat echo printf mkdir mktemp chmod rm cp ln dirname readlink ps; do
+  if [[ -e "/usr/bin/$cmd" || -L "/usr/bin/$cmd" ]]; then
+    /usr/bin/ln -s "/usr/bin/$cmd" "$TEST_DIR/install_bin/$cmd"
+  elif [[ -e "/bin/$cmd" || -L "/bin/$cmd" ]]; then
+    /usr/bin/ln -s "/bin/$cmd" "$TEST_DIR/install_bin/$cmd"
+  fi
+done
+output=$(PATH="$TEST_DIR/install_bin" HOME="$TEST_DIR" WAYLAND_DISPLAY="" XDG_CURRENT_DESKTOP="" KDE_FULL_SESSION="" "$COLOR_TOOL" --install 2>&1 || true)
+
+if [[ "$output" == *"python3 — required"* ]] &&
+   [[ "$output" == *"jq — required"* ]] &&
+   [[ "$output" == *"curl — required"* ]] &&
+   [[ "$output" == *"libnotify (notify-send)"* ]] &&
+   [[ "$output" == *"KDE Plasma on Wayland"* ]] &&
+   [[ "$output" == *"ImageMagick"* ]] &&
+   [[ "$output" == *"wl-clipboard"* ]]; then
+  echo "PASS"
+  passed=$((passed + 1))
+else
+  echo "FAIL"
+  echo "  Actual output: $output"
+fi
+
+# 15. Install — files placed in correct XDG directories
+it "installs files to XDG directories"
+# Clear any artifacts from earlier tests before verifying a clean install
+rm -rf "$XDG_DATA_HOME/color-tool" \
+       "$XDG_DATA_HOME/applications/color-tool.desktop" \
+       "$HOME/.local/bin" 2>/dev/null || true
+install_out=$("$COLOR_TOOL" --install 2>&1)
+if [[ -f "$XDG_DATA_HOME/color-tool/color-tool" ]] &&
+   [[ -f "$XDG_DATA_HOME/color-tool/wl-colorpicker-plasma.py" ]] &&
+   [[ -L "$HOME/.local/bin/color-tool" ]] &&
+   [[ -f "$XDG_DATA_HOME/applications/color-tool.desktop" ]] &&
+   [[ -f "$XDG_CONFIG_HOME/color-tool/config.toml" ]]; then
+  echo "PASS"
+  passed=$((passed + 1))
+else
+  echo "FAIL"
+  echo "  Install output: $install_out"
+  echo "  Files found:"
+  /usr/bin/find "$TEST_DIR/.local" "$TEST_DIR/.config" \( -type f -o -type l \) 2>/dev/null | /usr/bin/sort || true
+fi
+
+# 16. Uninstall — removes installed files, config is kept in non-interactive mode
+it "uninstalls installed files (keeps config)"
+uninstall_out=$("$COLOR_TOOL" --uninstall </dev/null 2>&1)
+if [[ ! -e "$HOME/.local/bin/color-tool" ]] &&
+   [[ ! -L "$HOME/.local/bin/color-tool" ]] &&
+   [[ ! -d "$XDG_DATA_HOME/color-tool" ]] &&
+   [[ ! -f "$XDG_DATA_HOME/applications/color-tool.desktop" ]] &&
+   [[ -f "$XDG_CONFIG_HOME/color-tool/config.toml" ]]; then
+  echo "PASS"
+  passed=$((passed + 1))
+else
+  echo "FAIL"
+  echo "  Uninstall output: $uninstall_out"
+  echo "  Files still present:"
+  /usr/bin/find "$TEST_DIR/.local" "$TEST_DIR/.config" \( -type f -o -type l \) 2>/dev/null | /usr/bin/sort || true
+fi
+
+# ── Cleanup ───────────────────────────────────────────────────────────────────
+echo "---------------------------------------"
+echo "Result: $passed/$total tests passed."
+rm -rf "$TEST_DIR"
+
+if [[ $passed -ne $total ]]; then
+  exit 1
+fi