Merge pull request 'feat: implement config management flags and documentation' (#6) from feat/manage-config into main

Reviewed-on: #4

.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

@@ -52,6 +52,9 @@ Options:
   --[no-]copy    Copy result to clipboard
   --[no-]notify  Show desktop notification
   --desktop      GUI mode: pick → copy → notify
+  --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
   --install      Install to ~/.local/share/ and symlink to ~/.local/bin/
   --help, -h     Show this help message
 ```
@@ -102,6 +105,34 @@ copy   = true   # copy result to clipboard
 notify = true   # show desktop notification with the copied value
 ```
 
+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).

color-tool

@@ -23,6 +23,7 @@ set -euo pipefail
 # Resolve the real directory of this script so we can find bundled helpers
 SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
 CONFIG_FILE="$HOME/.config/color-tool/config.toml"
+REPO_URL="https://git.rootiest.dev/rootiest/color-tool"
 
 # ── Initial Defaults ──────────────────────────────────────────────────────────
 
@@ -57,6 +58,156 @@ cli_output=""
 
 # ── Config Loader ─────────────────────────────────────────────────────────────
 
+get_config() {
+  if [[ ! -f "$CONFIG_FILE" ]]; then
+    echo "Error: Config file not found at $CONFIG_FILE" >&2
+    exit 1
+  fi
+  
+  local first_section=1
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    local stripped="${line%%#*}"
+    stripped="${stripped%"${stripped##*[![:space:]]}"}"
+    if [[ -z "$stripped" ]]; then
+      continue
+    fi
+    
+    if [[ "$stripped" =~ ^\[([A-Za-z_-]+)\]$ ]]; then
+      if [[ $first_section -eq 0 ]]; then
+        echo ""
+      fi
+      first_section=0
+      echo "$stripped"
+    elif [[ "$stripped" =~ ^[[:space:]]*([A-Za-z_]+)[[:space:]]*=[[:space:]]*(.*)$ ]]; then
+      local key="${BASH_REMATCH[1]}"
+      local val="${BASH_REMATCH[2]}"
+      printf "%-6s = %s\n" "$key" "$val"
+    fi
+  done < "$CONFIG_FILE"
+}
+
+set_config() {
+  local target_section="defaults"
+  if [[ $# -gt 0 ]]; then
+    if [[ "$1" == "default" || "$1" == "defaults" ]]; then
+      target_section="defaults"
+      shift
+    elif [[ "$1" == "desktop" ]]; then
+      target_section="desktop"
+      shift
+    fi
+  fi
+  
+  local new_output=""
+  local new_json=""
+  local new_swatch=""
+  local new_name=""
+  local new_copy=""
+  local new_pick=""
+  local new_notify=""
+  local new_alpha=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --output=*) new_output="${1#*=}" ;;
+      output=*) new_output="${1#*=}" ;;
+      --json) new_json="true" ;;
+      --no-json) new_json="false" ;;
+      --alpha) new_alpha="true" ;;
+      --no-alpha) new_alpha="false" ;;
+      --name) new_name="true" ;;
+      --no-name) new_name="false" ;;
+      --swatch) new_swatch="true" ;;
+      --no-swatch) new_swatch="false" ;;
+      --copy) new_copy="true" ;;
+      --no-copy) new_copy="false" ;;
+      --notify) new_notify="true" ;;
+      --no-notify) new_notify="false" ;;
+      --pick) new_pick="true" ;;
+      --no-pick) new_pick="false" ;;
+      -*) 
+        echo "Error: Unknown option for --set-config: $1" >&2
+        exit 1
+        ;;
+      *)
+        echo "Error: Unknown argument for --set-config: $1" >&2
+        exit 1
+        ;;
+    esac
+    shift
+  done
+  
+  if [[ -n "$new_output" ]]; then
+    new_output="${new_output#\"}"
+    new_output="${new_output%\"}"
+  fi
+
+  if [[ ! -f "$CONFIG_FILE" ]]; then
+    echo "Error: Config file not found at $CONFIG_FILE. Run --install first." >&2
+    exit 1
+  fi
+  
+  local temp_file
+  temp_file="$(mktemp)"
+  local current_section=""
+  
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    local original_line="$line"
+    local parsed_line="${line%%#*}"
+    
+    if [[ "$parsed_line" =~ ^\[([A-Za-z_-]+)\]$ ]]; then
+      current_section="${BASH_REMATCH[1]}"
+      echo "$original_line" >> "$temp_file"
+      continue
+    fi
+    
+    if [[ "$current_section" == "$target_section" && "$parsed_line" =~ ^[[:space:]]*([A-Za-z_]+)[[:space:]]*= ]]; then
+      local key="${BASH_REMATCH[1]}"
+      local new_val=""
+      case "$key" in
+        output)
+          if [[ -n "$new_output" ]]; then new_val="\"$new_output\""; fi
+          ;;
+        json)
+          if [[ -n "$new_json" ]]; then new_val="$new_json"; fi
+          ;;
+        alpha)
+          if [[ -n "$new_alpha" ]]; then new_val="$new_alpha"; fi
+          ;;
+        swatch)
+          if [[ -n "$new_swatch" ]]; then new_val="$new_swatch"; fi
+          ;;
+        name)
+          if [[ -n "$new_name" ]]; then new_val="$new_name"; fi
+          ;;
+        copy)
+          if [[ -n "$new_copy" ]]; then new_val="$new_copy"; fi
+          ;;
+        pick)
+          if [[ -n "$new_pick" ]]; then new_val="$new_pick"; fi
+          ;;
+        notify)
+          if [[ -n "$new_notify" ]]; then new_val="$new_notify"; fi
+          ;;
+      esac
+      
+      if [[ -n "$new_val" ]]; then
+        if [[ "$original_line" =~ ^([[:space:]]*[A-Za-z_]+[[:space:]]*=[[:space:]]*)([^[:space:]#]+)(.*)$ ]]; then
+           echo "${BASH_REMATCH[1]}$new_val${BASH_REMATCH[3]}" >> "$temp_file"
+           continue
+        elif [[ "$original_line" =~ ^([[:space:]]*[A-Za-z_]+[[:space:]]*=[[:space:]]*)(.*)$ ]]; then
+           echo "${BASH_REMATCH[1]}$new_val" >> "$temp_file"
+           continue
+        fi
+      fi
+    fi
+    
+    echo "$original_line" >> "$temp_file"
+  done < "$CONFIG_FILE"
+  
+  mv "$temp_file" "$CONFIG_FILE"
+}
+
 # Parse ~/.config/color-tool/config.toml and apply [defaults] and [desktop] values.
 load_config() {
   [[ ! -f "$CONFIG_FILE" ]] && return 0
@@ -98,6 +249,37 @@ load_config() {
   done <"$CONFIG_FILE"
 }
 
+write_default_config() {
+  mkdir -p "$(dirname "$CONFIG_FILE")"
+  cat >"$CONFIG_FILE" <<EOF
+# color-tool configuration
+# Source: $REPO_URL
+
+[defaults]
+# 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 from thecolorapi.com
+copy   = false  # copy result to clipboard
+pick   = false  # auto-launch color picker when invoked with no arguments
+notify = false  # show desktop notification
+
+[desktop]
+# 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
+EOF
+}
+
+reset_config() {
+  write_default_config
+  echo "Configuration reset to defaults: $CONFIG_FILE"
+}
+
 # ── Help ──────────────────────────────────────────────────────────────────────
 
 show_help() {
@@ -121,9 +303,12 @@ show_help() {
   printf "  ${bold}${cyan}--[no-]json${reset}    Output as a JSON table of selected formats\n"
   printf "  ${bold}${cyan}--[no-]name${reset}    Fetch nearest color name from thecolorapi.com ${dim}(requires curl, jq)${reset}\n"
   printf "  ${bold}${cyan}--[no-]swatch${reset}  Include a color swatch in the terminal output\n"
-  printf "  ${bold}${cyan}--[no-]copy${reset}    Copy result to clipboard ${dim}(wl-copy preferred, xclip as fallback)${reset}\n"
+  printf "  ${bold}${cyan}--[no-]copy${reset}    Copy result to clipboard ${dim}(wl-clipboard preferred, xclip as fallback)${reset}\n"
   printf "  ${bold}${cyan}--[no-]notify${reset}  Show desktop notification ${dim}(on by default in --desktop)${reset}\n"
   printf "  ${bold}${cyan}--desktop${reset}      GUI mode: pick → copy → notify ${dim}(for app menu / .desktop launcher)${reset}\n"
+  printf "  ${bold}${cyan}--get-config${reset}   Print the current configuration\n"
+  printf "  ${bold}${cyan}--set-config${reset}   Update the configuration ${dim}(e.g. --set-config desktop --copy)${reset}\n"
+  printf "  ${bold}${cyan}--reset-config${reset} Restore the configuration file to its default values\n"
   printf "  ${bold}${cyan}--install${reset}      Install to ~/.local/share/color-tool/ and symlink into ~/.local/bin/\n"
   printf "  ${bold}${cyan}--help${reset}, ${bold}${cyan}-h${reset}     Show this help message\n\n"
 
@@ -278,30 +463,8 @@ do_install() {
 
   local config_dir="$HOME/.config/color-tool"
   local config_file="$config_dir/config.toml"
-  mkdir -p "$config_dir"
   if [[ ! -f "$config_file" ]]; then
-    cat >"$config_file" <<'EOF'
+    write_default_config
-# color-tool configuration
-# https://github.com/rootiest/color-tool
-
-[defaults]
-# 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 from thecolorapi.com
-copy   = false  # copy result to clipboard
-pick   = false  # auto-launch color picker when invoked with no arguments
-notify = false  # show desktop notification
-
-[desktop]
-# 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
-EOF
     printf "  config  %s  (sample created)\n" "$config_file"
   else
     printf "  config  %s\n" "$config_file"
@@ -521,6 +684,19 @@ while [[ $# -gt 0 ]]; do
     do_install
     exit 0
     ;;
+  --get-config)
+    get_config
+    exit 0
+    ;;
+  --set-config)
+    shift
+    set_config "$@"
+    exit 0
+    ;;
+  --reset-config)
+    reset_config
+    exit 0
+    ;;
   -*)
     echo "Unknown option: $1" >&2
     exit 1

tests/run_tests.sh

@@ -0,0 +1,216 @@
+#!/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"
+
+export PATH="$BIN_DIR"
+export HOME="$TEST_DIR"
+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"
+
+# ── Cleanup ───────────────────────────────────────────────────────────────────
+echo "---------------------------------------"
+echo "Result: $passed/$total tests passed."
+rm -rf "$TEST_DIR"
+
+if [[ $passed -ne $total ]]; then
+  exit 1
+fi