Taskfile.yml

# Taskfile.yml for Clash Royale API project
# Requires: https://taskfile.dev/installation/

version: '3'

vars:
  PROJECT_NAME: clash-royale-api
  DATA_DIR: data
  TEST_PLAYER_TAG: '#PLAYERTAG'
  CR_API_BIN: bin/cr-api

dotenv: ['.env']

binary_precondition: &binary_precondition
  - sh: test -x {{.CR_API_BIN}}
    msg: "cr-api binary not found. Build it with: task build"

tasks:
  # Basic Tasks
  default:
    desc: Show available tasks
    cmds:
      - task --list
# Project Setup
  setup:
    desc: Set up the development environment
    cmds:
      - echo "Setting up development environment..."
      - task: build
      - echo "Creating data directories..."
      - mkdir -p {{.DATA_DIR}}/{players,clans,analysis,static,reference}
      - mkdir -p scripts
      - echo "Copying example .env file..."
      - test -f .env || cp .env.example .env 2>/dev/null || echo "No .env.example found, creating basic .env"
      - test -f .env || echo -e "CLASH_ROYALE_API_TOKEN=your_api_token_here\nDATA_DIR={{.DATA_DIR}}" > .env
      - echo "✅ Setup complete!"
      - echo "Please edit .env file with your API token"

  install:
    desc: Build Go binaries
    summary: |
      Alias for 'task build'. Builds Go binaries for local development.
    cmds:
      - task: build

  build:
    desc: Build Go CLI binaries for local development
    cmds:
      - echo "Building Go binaries for local development..."
      - mkdir -p bin
      - go mod download
      - |
        VERSION=$(git describe --tags --always 2>/dev/null || echo 'dev')
        COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo 'unknown')
        BUILD_TIME=$(date -u '+%Y-%m-%dT%H:%M:%SZ')

        go build \
          -ldflags="-s -w -X main.version=$VERSION -X main.commit=$COMMIT -X main.buildTime=$BUILD_TIME" \
          -o bin/cr-api ./cmd/cr-api
      - echo "✅ Go binary built successfully!"
# Basic Player Operations
  run:
    desc: Analyze a player's collection using the Go CLI
    summary: |
      Analyze a player's card collection and display upgrade needs using the Go binary

      Args:
        player: Player tag to analyze (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        CLEAN_TAG="${PLAYER_TAG#\#}"
        echo "Analyzing $CLEAN_TAG with Go CLI..."
        {{.CR_API_BIN}} analyze --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}"
    preconditions: *binary_precondition

  run-with-save:
    desc: Run Go CLI analysis and save results to JSON files
    summary: |
      Analyze a player and save the results to JSON files using the Go binary

      Args:
        player: Player tag to analyze (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        CLEAN_TAG="${PLAYER_TAG#\#}"
        echo "Analyzing and saving results for $CLEAN_TAG..."
        {{.CR_API_BIN}} analyze --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --save
    preconditions: *binary_precondition
# Export Operations
  export-csv:
    desc: Export player and reference data to CSV using the Go CLI
    summary: |
      Export player's card collection and other data to CSV using the Go binary

      Args:
        player: Player tag to analyze (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        CLEAN_TAG="${PLAYER_TAG#\#}"
        echo "Exporting player data for $CLEAN_TAG to CSV..."
        {{.CR_API_BIN}} player --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --export-csv --save

        echo "Exporting card database to CSV..."
        {{.CR_API_BIN}} cards --data-dir "{{.DATA_DIR}}" --export-csv
    preconditions: *binary_precondition

  export-all:
    desc: Export all available data types for a player using the Go CLI
    summary: |
      Export player data, card database, and save analysis results using the Go binary

      Args:
        player: Player tag to analyze (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        CLEAN_TAG="${PLAYER_TAG#\#}"
        echo "Exporting full dataset for $CLEAN_TAG..."
        {{.CR_API_BIN}} player --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --chests --export-csv --save
        {{.CR_API_BIN}} cards --data-dir "{{.DATA_DIR}}" --export-csv
        {{.CR_API_BIN}} analyze --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --save
    preconditions: *binary_precondition

  export-player:
    desc: Export player profile data to CSV
    summary: |
      Export player profile information to CSV using the export subcommand

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Exporting player data for $CLEAN_TAG..."
        {{.CR_API_BIN}} export player --tag "$CLEAN_TAG"
    preconditions: *binary_precondition

  export-analysis:
    desc: Export card collection analysis to CSV
    summary: |
      Export detailed card collection analysis including upgrade paths to CSV

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Exporting analysis data for $CLEAN_TAG..."
        {{.CR_API_BIN}} export analysis --tag "$CLEAN_TAG"
    preconditions: *binary_precondition

  export-battles:
    desc: Export battle log to CSV
    summary: |
      Export recent battle history with deck compositions and outcomes to CSV

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Exporting battle log for $CLEAN_TAG..."
        {{.CR_API_BIN}} export battles --tag "$CLEAN_TAG"
    preconditions: *binary_precondition

  export-events-csv:
    desc: Export event deck data to CSV using export subcommand
    summary: |
      Export event deck performance data to CSV format using the export subcommand

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Exporting event data for $CLEAN_TAG..."
        {{.CR_API_BIN}} export events --tag "$CLEAN_TAG"
    preconditions: *binary_precondition

  export-player-all:
    desc: Export all available player data using export subcommand
    summary: |
      Export all available data types for a player in one command using export all

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Exporting all data for $CLEAN_TAG..."
        {{.CR_API_BIN}} export all --tag "$CLEAN_TAG"
    preconditions: *binary_precondition
# Deck Building Operations
  build-deck:
    desc: Build an optimized 1v1 ladder deck from the latest analysis
    summary: |
      Runs card analysis (saved) and then builds a recommended 1v1 ladder deck.

      Args:
        player: Player tag to use (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        CLEAN_TAG="${PLAYER_TAG#\#}"

        echo "Running analysis for $CLEAN_TAG..."
        {{.CR_API_BIN}} analyze --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --save

        ANALYSIS_FILE="{{.DATA_DIR}}/analysis/${PLAYER_TAG}.json"
        if [ ! -f "$ANALYSIS_FILE" ]; then
          echo "Expected analysis file not found at $ANALYSIS_FILE" >&2
          exit 1
        fi

        echo "Building optimized 1v1 deck from latest analysis..."
        {{.CR_API_BIN}} deck build --from-analysis "$ANALYSIS_FILE"
    preconditions: *binary_precondition

  war-decks:
    desc: Build a 4-deck war lineup with no repeated cards
    summary: |
      Builds an optimized 4-deck war lineup using archetype-based deck building.
      Automatically finds the best combination of archetypes to maximize deck quality
      while ensuring zero card overlap across all 4 decks.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        CLEAN_TAG="${PLAYER_TAG#\#}"
        echo "Building war deck lineup for $CLEAN_TAG..."
        {{.CR_API_BIN}} deck war --tag "$CLEAN_TAG"
    preconditions: *binary_precondition

  deck-optimize:
    desc: Optimize existing deck with available cards
    summary: |
      Optimize an existing deck by suggesting card replacements from your collection
      that maintain archetype identity while improving overall deck quality.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Optimizing deck for $CLEAN_TAG..."
        {{.CR_API_BIN}} deck optimize --tag "$CLEAN_TAG" --max-changes 4 --verbose
    preconditions: *binary_precondition

  deck-budget:
    desc: Find budget-optimized decks with minimal upgrade investment
    summary: |
      Analyze all viable decks and rank them by upgrade efficiency (ROI).
      Shows which decks give you the best competitive value for your upgrade resources.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Finding budget decks for $CLEAN_TAG..."
        {{.CR_API_BIN}} deck budget --tag "$CLEAN_TAG" --top-n 10 --sort-by roi
    preconditions: *binary_precondition

  deck-fuzz-build:
    desc: Generate fuzz data and build data-driven deck
    summary: |
      Run Monte Carlo deck fuzzing to generate data, then build a deck using
      fuzz integration for data-driven card selection. Cards that perform well
      in top-scoring fuzz decks receive a scoring boost.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
        count: Number of decks to fuzz (default: 1000)
        weight: Fuzz scoring weight 0.0-1.0 (default: 0.15)

      Example:
        task deck-fuzz-build -- #PLAYER_TAG 2000 0.20

      Env vars:
        FUZZ_STORAGE: Path to fuzz storage db (default: ~/.cr-api/fuzz_top_decks.db)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        # Extract optional count and weight from args
        COUNT="{{.FUZZ_COUNT}}"
        WEIGHT="{{.FUZZ_WEIGHT}}"
        STORAGE="${FUZZ_STORAGE:-$HOME/.cr-api/fuzz_top_decks.db}"

        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          echo "Usage: task deck-fuzz-build -- [#PLAYER_TAG] [count] [weight]" >&2
          echo "Example: task deck-fuzz-build -- #PLAYER_TAG 2000 0.20" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "================================"
        echo "Deck Fuzz + Build Workflow"
        echo "================================"
        echo "Player: $CLEAN_TAG"
        echo "Fuzz count: ${COUNT:-1000}"
        echo "Fuzz weight: ${WEIGHT:-0.15}"
        echo "Storage: $STORAGE"
        echo ""

        # Step 1: Run deck fuzz (resume from stored top decks for better results)
        echo "Step 1: Generating $COUNT fuzz decks (resuming from stored top 50)..."
        {{.CR_API_BIN}} deck fuzz \
          --tag "$CLEAN_TAG" \
          --count "${COUNT:-1000}" \
          --workers 4 \
          --resume-from 50 \
          --save-top \
          --storage "$STORAGE"

        echo ""
        echo "Step 2: Building deck with fuzz integration..."

        # Step 2: Build deck with fuzz integration (saves to file)
        {{.CR_API_BIN}} deck build \
          --tag "$CLEAN_TAG" \
          --fuzz-storage "$STORAGE" \
          --fuzz-weight "${WEIGHT:-0.15}" \
          --fuzz-deck-limit 100 \
          --save

        echo ""
        echo "Step 3: Evaluating built deck..."

        # Extract deck cards from the most recent deck file
        DECK_FILE=$(ls -t {{.DATA_DIR}}/decks/*_${CLEAN_TAG}_*.json 2>/dev/null | head -1)
        if [ -n "$DECK_FILE" ]; then
          # Extract deck array and join with dashes (JSON uses lowercase "deck")
          if command -v jq >/dev/null 2>&1; then
            DECK_STRING=$(jq -r '.deck | join("-")' "$DECK_FILE" 2>/dev/null)
          else
            # Fallback: extract with sed/awk
            DECK_STRING=$(grep -A 20 '"deck"' "$DECK_FILE" | grep '"' | grep -v 'deck\|"\[,\]' | sed 's/^"//' | sed 's/"$//' | tr '\n' '-' | sed 's/-$//')
          fi

          if [ -n "$DECK_STRING" ]; then
            {{.CR_API_BIN}} deck evaluate \
              --deck "$DECK_STRING" \
              --tag "$CLEAN_TAG" \
              --format detailed
          fi
        fi

        echo ""
        echo "✅ Fuzz-integrated deck complete!"
        echo ""
        echo "To view stored fuzz data:"
        echo "  {{.CR_API_BIN}} deck fuzz list --storage $STORAGE --limit 20"
    vars:
      FUZZ_COUNT:
        sh: test -z "{{.ARGS}}" && echo "1000" || echo "{{.ARGS}}" | awk '{print $2}' | grep -E '^[0-9]+$' || echo "1000"
      FUZZ_WEIGHT:
        sh: test -z "{{.ARGS}}" && echo "0.15" || echo "{{.ARGS}}" | awk '{print $3}' | grep -E '^[0-9]' || echo "0.15"
    preconditions: *binary_precondition

  deck-fuzz-genetic-quick:
    desc: Run a shorter genetic fuzz pass and save top decks
    summary: |
      Runs genetic deck fuzzing and saves the top decks to storage.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
        seed: Optional seed override (second arg)

      Example:
        task deck-fuzz-genetic-quick -- #PLAYER_TAG 42

      Env vars:
        FUZZ_STORAGE: Path to fuzz storage db (default: ~/.cr-api/fuzz_top_decks.db)
    cmds:
      - |
        PLAYER_TAG="{{.FUZZ_PLAYER_TAG}}"
        SEED="{{.FUZZ_SEED}}"
        STORAGE="${FUZZ_STORAGE:-$HOME/.cr-api/fuzz_top_decks.db}"

        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          echo "Usage: task deck-fuzz-genetic-quick -- [#PLAYER_TAG] [seed]" >&2
          exit 1
        fi

        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Genetic fuzz (quick) for $CLEAN_TAG"
        echo "Storage: $STORAGE"
        echo ""

        {{.CR_API_BIN}} deck fuzz \
          --tag "$CLEAN_TAG" \
          --mode genetic \
          --ga-population 30000 \
          --ga-generations 30000 \
          --ga-elite-count 200 \
          --ga-parallel-eval \
          --ga-tournament-size 7 \
          --seed "${SEED:-$RANDOM}" \
          --top 100 \
          --resume-from 100 \
          --save-top \
          --storage "$STORAGE"
    vars:
      FUZZ_PLAYER_TAG:
        sh: test -z "{{.ARGS}}" && echo "" || echo "{{.ARGS}}" | awk '{print $1}'
      FUZZ_SEED:
        sh: test -z "{{.ARGS}}" && echo "" || echo "{{.ARGS}}" | awk '{print $2}'
    preconditions: *binary_precondition

  deck-fuzz-genetic-overnight:
    desc: Run a long genetic fuzz pass and save top decks
    summary: |
      Runs a long genetic deck fuzzing job for building a deck corpus.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
        seed: Optional seed override (second arg)

      Example:
        task deck-fuzz-genetic-overnight -- #PLAYER_TAG 1234

      Env vars:
        FUZZ_STORAGE: Path to fuzz storage db (default: ~/.cr-api/fuzz_top_decks.db)
        FUZZ_GA_POPULATION: Override GA population size (default: 60000)
        FUZZ_GA_GENERATIONS: Override GA generations (default: 64000)
        FUZZ_VERBOSE: Set to 1/true for verbose output (default: off)
    cmds:
      - |
        PLAYER_TAG="{{.FUZZ_PLAYER_TAG}}"
        SEED="{{.FUZZ_SEED}}"
        STORAGE="${FUZZ_STORAGE:-$HOME/.cr-api/fuzz_top_decks.db}"
        POPULATION="${FUZZ_GA_POPULATION:-60000}"
        GENERATIONS="${FUZZ_GA_GENERATIONS:-64000}"
        SEED_VALUE="${SEED:-$RANDOM}"
        VERBOSE=""
        if [ "${FUZZ_VERBOSE}" = "1" ] || [ "${FUZZ_VERBOSE}" = "true" ]; then
          VERBOSE="--verbose"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          echo "Usage: task deck-fuzz-genetic-overnight -- [#PLAYER_TAG] [seed]" >&2
          exit 1
        fi

        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Genetic fuzz (overnight) for $CLEAN_TAG"
        echo "Storage: $STORAGE"
        echo "Population: $POPULATION | Generations: $GENERATIONS"
        echo "Seed: $SEED_VALUE"
        echo ""

        {{.CR_API_BIN}} deck fuzz \
          --tag "$CLEAN_TAG" \
          --mode genetic \
          --ga-population "$POPULATION" \
          --ga-generations "$GENERATIONS" \
          --ga-elite-count 100 \
          --ga-parallel-eval \
          --ga-tournament-size 7 \
          --ga-convergence-generations 0 \
          --ga-island-model \
          --ga-island-count 4 \
          --ga-migration-interval 15 \
          --ga-migration-size 2 \
          --seed "$SEED_VALUE" \
          --top 100 \
          --resume-from 100 \
          --save-top \
          --storage "$STORAGE" \
          $VERBOSE
    vars:
      FUZZ_PLAYER_TAG:
        sh: test -z "{{.ARGS}}" && echo "" || echo "{{.ARGS}}" | awk '{print $1}'
      FUZZ_SEED:
        sh: test -z "{{.ARGS}}" && echo "" || echo "{{.ARGS}}" | awk '{print $2}'
    preconditions: *binary_precondition

  # Event Deck Tasks
  scan-events:
    desc: Scan battle logs for event decks using Go CLI
    summary: |
      Automatically scan and import event decks from battle logs using the Go binary

      Args:
        player: Player tag to scan (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
        days: Number of days to scan back (default: 7)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        # Extract days from end of args if present, otherwise use default
        DAYS="{{.DAYS_BACK}}"

        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Scanning event decks for $CLEAN_TAG (last $DAYS days)..."
        {{.CR_API_BIN}} events scan --tag "$CLEAN_TAG" --days "$DAYS" --data-dir "{{.DATA_DIR}}" --save
    vars:
      DAYS_BACK:
        sh: "echo '{{.ARGS}}' | grep -oE '[0-9]+$' || echo '7'"
    preconditions: *binary_precondition

  export-events:
    desc: Export event decks to CSV using Go CLI
    summary: |
      Export event decks with performance data to CSV using the Go binary

      Args:
        player: Player tag to export (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Exporting event decks for $CLEAN_TAG to CSV..."
        {{.CR_API_BIN}} events list --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --export-csv
    preconditions: *binary_precondition

  export-decks:
    desc: Export event decks in deck builder format using Go CLI
    summary: |
      Export event decks for sharing on deck builder sites using the Go binary

      Args:
        player: Player tag to export (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Exporting event decks for $CLEAN_TAG in deck builder format..."
        # Note: The Go CLI doesn't have a specific deck builder export yet,
        # so we'll export the event list which can be used for deck building
        {{.CR_API_BIN}} events list --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --export-csv
        echo "Deck builder format exported to CSV - can be imported into deck building sites"
    preconditions: *binary_precondition

  analyze-events:
    desc: Analyze event deck performance using Go CLI
    summary: |
      Analyze event deck performance with detailed insights using the Go binary

      Args:
        player: Player tag to analyze (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Analyzing event performance for $CLEAN_TAG..."
        {{.CR_API_BIN}} events analyze --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --min-battles 5 --export-csv
    preconditions: *binary_precondition

  sync-events:
    desc: Sync recent event activity using Go CLI
    summary: |
      Sync and analyze recent event activity from battle logs using the Go binary

      Args:
        player: Player tag to sync (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Syncing recent events for $CLEAN_TAG (last 7 days)..."
        {{.CR_API_BIN}} events scan --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --days 7 --save
        echo "Sync complete! Use 'task analyze-events -- $CLEAN_TAG' to analyze the data."
    preconditions: *binary_precondition

  # Archetype Analysis Tasks
  analyze-archetypes:
    desc: Analyze archetype variety and upgrade costs using Go CLI
    summary: |
      Generate decks for all 8 archetypes and calculate upgrade costs to target level

      Args:
        player: Player tag to analyze (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
        target-level: Target competitive card level (default: 11)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Analyzing archetype variety for $CLEAN_TAG..."
        {{.CR_API_BIN}} archetypes --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}"
    preconditions: *binary_precondition

  export-archetypes:
    desc: Analyze and export archetype data to CSV using Go CLI
    summary: |
      Generate archetype analysis and export to CSV with upgrade details

      Args:
        player: Player tag to analyze (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Analyzing and exporting archetype data for $CLEAN_TAG to CSV..."
        {{.CR_API_BIN}} archetypes --tag "$CLEAN_TAG" --data-dir "{{.DATA_DIR}}" --export-csv --save
    preconditions: *binary_precondition

  # Evolution Tasks
  evolution-recommend:
    desc: Recommend optimal evolutions based on shards and card levels
    summary: |
      Analyze your evolution shard inventory and card levels to recommend
      which evolutions would have the biggest impact on your deck viability.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Recommending evolutions for $CLEAN_TAG..."
        {{.CR_API_BIN}} evolutions recommend --tag "$CLEAN_TAG"
    preconditions: *binary_precondition

  # Upgrade Analysis Tasks
  upgrade-impact:
    desc: Analyze which card upgrades have biggest impact on deck viability
    summary: |
      Analyze your card collection and identify which upgrades would unlock
      the most new viable decks or improve existing deck quality the most.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Analyzing upgrade impact for $CLEAN_TAG..."
        {{.CR_API_BIN}} upgrade-impact --tag "$CLEAN_TAG" --top 10
    preconditions: *binary_precondition

  what-if:
    desc: Simulate deck changes with upgraded cards
    summary: |
      Simulate what decks would be available if you upgraded specific cards.
      Useful for planning upgrade investments.

      Args:
        upgrades: Card upgrade specs in format "CardName:Level" (required)
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)

      Example:
        task what-if -- Knight:14 Archers:13 Fireball:12
        task what-if -- #PLAYER_TAG Knight:14 Archers:13
    cmds:
      - |
        # Parse arguments - first check if first arg is a player tag
        ARGS="{{.CLI_ARGS}}"
        if [ -z "$ARGS" ]; then
          echo "Please provide upgrade specifications (e.g., Knight:14 Archers:13)" >&2
          echo "Usage: task what-if -- [#PLAYER_TAG] CardName:Level [CardName:Level...]" >&2
          exit 1
        fi

        # Split args into array
        read -ra ARG_ARRAY <<< "$ARGS"

        # Check if first arg is a player tag (starts with # or looks like a tag)
        FIRST_ARG="${ARG_ARRAY[0]}"
        if [[ "$FIRST_ARG" =~ ^#.+ ]] || [[ -z "${DEFAULT_PLAYER_TAG}" && ! "$FIRST_ARG" =~ : ]]; then
          PLAYER_TAG="$FIRST_ARG"
          UPGRADE_ARGS=("${ARG_ARRAY[@]:1}")
        else
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
          UPGRADE_ARGS=("${ARG_ARRAY[@]}")
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        if [ ${#UPGRADE_ARGS[@]} -eq 0 ]; then
          echo "Please provide at least one upgrade specification (e.g., Knight:14)" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        # Build upgrade flags
        UPGRADE_FLAGS=""
        for upgrade in "${UPGRADE_ARGS[@]}"; do
          UPGRADE_FLAGS="$UPGRADE_FLAGS --upgrade $upgrade"
        done

        echo "Simulating upgrades for $CLEAN_TAG: ${UPGRADE_ARGS[*]}"
        {{.CR_API_BIN}} what-if --tag "$CLEAN_TAG" $UPGRADE_FLAGS --show-decks
    preconditions: *binary_precondition

  playstyle:
    desc: Analyze player's playstyle and recommend decks
    summary: |
      Analyze your battle history to identify your preferred playstyle
      (aggro, control, beatdown, etc.) and recommend decks that match it.

      Args:
        player: Player tag (optional, will use DEFAULT_PLAYER_TAG from .env if not provided)
    cmds:
      - |
        PLAYER_TAG="{{.CLI_ARGS}}"
        if [ -z "$PLAYER_TAG" ]; then
          PLAYER_TAG="${DEFAULT_PLAYER_TAG}"
        fi

        if [ -z "$PLAYER_TAG" ]; then
          echo "Please provide a player tag or set DEFAULT_PLAYER_TAG in .env" >&2
          exit 1
        fi

        # Remove any surrounding quotes from PLAYER_TAG
        CLEAN_TAG=$(echo "$PLAYER_TAG" | sed "s/^'//;s/'$//" | sed 's/^"//;s/"$//')
        CLEAN_TAG="${CLEAN_TAG#\#}"

        echo "Analyzing playstyle for $CLEAN_TAG..."
        {{.CR_API_BIN}} playstyle --tag "$CLEAN_TAG" --recommend-decks --save
    preconditions: *binary_precondition
# Development Commands
  test:
    desc: Run Go tests
    summary: |
      Run all tests for the project.
      - Go tests: Run all Go package tests with coverage
    cmds:
      - task: test-go

  lint:
    desc: Run linting on Go code
    summary: |
      Run linter on Go code
      - golangci-lint (comprehensive linting)
      - go vet (built-in vet)
      - check-stale-beads-refs (detects orphan clash-royale-api-* IDs)
    cmds:
      - echo "Running golangci-lint..."
      - |
        if command -v golangci-lint >/dev/null 2>&1; then
          golangci-lint run --timeout=5m
        else
          echo "golangci-lint not found, running go vet..."
        fi
      - go vet ./...
      - bash scripts/check-stale-beads-refs.sh

  lint-beads-refs:
    desc: Detect stale clash-royale-api-* references in code/docs
    summary: |
      Cross-checks every clash-royale-api-<id> mention in source code,
      tests, scripts, and markdown against the live bd issue list.
      Fails on stale references when invoked with `--strict` (intended
      for CI / pre-PR use).
    cmds:
      - bash scripts/check-stale-beads-refs.sh {{.CLI_ARGS}}

  lint-quality:
    desc: Run quality linting (CI hard-fail for new violations)
    summary: |
      Run golangci-lint configured to fail CI on new violations only.
      This checks for new lint issues relative to origin/main.
      Use this to validate your changes won't break CI.
    cmds:
      - echo "Running quality lint (checks for new violations only)..."
      - |
        if command -v golangci-lint >/dev/null 2>&1; then
          golangci-lint run --timeout=5m --new-from-rev=origin/main
        else
          echo "golangci-lint not found. Install with: task install-tools"
          exit 1
        fi

  format:
    desc: Format Go code with gofumpt
    summary: |
      Format Go code with gofumpt (stricter than gofmt)
      Falls back to goimports/gofmt if gofumpt not available
    cmds:
      - echo "Formatting Go code..."
      - |
        if command -v gofumpt >/dev/null 2>&1; then
          gofumpt -w -extra .
        elif command -v goimports >/dev/null 2>&1; then
          goimports -w $(go list -f '{{.Dir}}' ./...)
        else
          gofmt -w $(go list -f '{{.Dir}}' ./...)
        fi

  setup-githooks:
    desc: Install git hooks for auto-formatting
    summary: |
      Install git pre-push hook that auto-formats code before pushing.
      This prevents CI failures due to formatting issues.
    cmds:
      - bash scripts/setup-githooks.sh
    preconditions:
      - sh: test -f scripts/setup-githooks.sh
        msg: "setup-githooks.sh not found"

  clean:
    desc: Clean up generated files
    summary: |
      Remove all generated files and directories, including the data/ directory.
    cmds:
      - echo "Cleaning up..."
      - rm -rf {{.DATA_DIR}}/
      - echo "✅ Clean complete!"

  clean-data:
    desc: Clean up generated data files (keeps example configs)
    summary: |
      Remove temporary/generated files from data/ directory while preserving
      tracked example files (upgrade_plan_example.json, evolution_shards.example.json,
      static/cards_stats.json, README.md)
    cmds:
      - |
        echo "Cleaning data/ directory (preserving tracked files)..."
        # Remove generated directories
        rm -rf {{.DATA_DIR}}/analysis/ {{.DATA_DIR}}/decks/ {{.DATA_DIR}}/csv/ {{.DATA_DIR}}/evaluations/
        rm -rf {{.DATA_DIR}}/players/ {{.DATA_DIR}}/reports/ {{.DATA_DIR}}/clans/ {{.DATA_DIR}}/reference/
        # Remove generated files (excluding README.md)
        find {{.DATA_DIR}} -maxdepth 1 -type f \( -name "*.md" ! -name "README.md" -o -name "*.txt" -o -name "*.csv" \) -delete 2>/dev/null || true
        rm -f {{.DATA_DIR}}/decks_to_compare.json {{.DATA_DIR}}/evolution_shards.json
        rm -f {{.DATA_DIR}}/static/cards.json
        # Restore tracked files if they were accidentally deleted
        git checkout {{.DATA_DIR}}/upgrade_plan_example.json 2>/dev/null || true
        git checkout {{.DATA_DIR}}/evolution_shards.example.json 2>/dev/null || true
        git checkout {{.DATA_DIR}}/static/cards_stats.json 2>/dev/null || true
        git checkout {{.DATA_DIR}}/README.md 2>/dev/null || true
        echo "✅ Cleanup complete. Kept: upgrade_plan_example.json, evolution_shards.example.json, static/cards_stats.json, README.md"

  status:
    desc: Show project status
    summary: |
      Display project configuration status, including environment variables and data directory.
    cmds:
      - 'echo "=== Project Status ==="'
      - 'echo "Project name: {{.PROJECT_NAME}}"'
      - 'echo "Data directory: {{.DATA_DIR}}"'
      - echo ''
      - 'echo "=== Environment ==="'
      - 'test -f .env && echo "✅ .env file exists" || echo "❌ .env file missing"'
      - 'test -f .env && grep -q "CLASH_ROYALE_API_TOKEN=" .env && echo "✅ API token configured" || echo "❌ API token not configured"'

  test-go:
    desc: Run Go unit tests only
    summary: |
      Run Go unit tests with coverage and race detection.
      Integration tests (requires API token) are excluded by default.
      Use 'task test-integration' to run integration tests.
    cmds:
      - echo "Running Go unit tests (excluding integration)..."
      - |
        if [ -f ".env" ]; then
          # Export only valid variable names from .env (skip lines with # or invalid names)
          set -a
          while IFS='=' read -r key value; do
            # Skip lines starting with #, empty lines, or keys with invalid characters
            if [[ ! "$key" =~ ^[[:space:]]*# ]] && [[ "$key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
              export "$key=$value"
            fi
          done < .env
          set +a
        fi && \
        go test -v -race -tags='!integration' -covermode=atomic -coverpkg=./... -coverprofile=coverage.out ./...
      - |
        if [ -f "coverage.out" ]; then
          go tool cover -func=coverage.out | tail -1
          go tool cover -html=coverage.out -o coverage.html
        else
          echo "Coverage report not available"
        fi

  test-integration:
    desc: Run integration tests (requires API token)
    summary: |
      Run integration tests that connect to the live Clash Royale API.
      Requires CLASH_ROYALE_API_TOKEN in .env file.

      Note: Integration tests are excluded from CI to avoid IP rate limiting issues.
    cmds:
      - echo "Running integration tests (requires valid API token)..."
      - |
        if [ -f ".env" ]; then
          # Export environment variables from .env
          set -a
          while IFS='=' read -r key value; do
            if [[ ! "$key" =~ ^[[:space:]]*# ]] && [[ "$key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
              export "$key=$value"
            fi
          done < .env
          set +a
        fi
      - |
        if [ -z "$CLASH_ROYALE_API_TOKEN" ]; then
          echo "❌ CLASH_ROYALE_API_TOKEN not found in .env file"
          echo "Integration tests require a valid API token from developer.clashroyale.com"
          exit 1
        fi
      - |
        printf 'Testing with token: %.20s...\n' "$CLASH_ROYALE_API_TOKEN"
      - go test -v -race -tags=integration ./...

  # CI/CD Tasks
  install-tools:
    desc: Install development tools
    summary: |
      Install required development tools for the project
    cmds:
      - echo "Installing development tools..."
      - |
        # Install golangci-lint
        if ! command -v golangci-lint &> /dev/null; then
          echo "Installing golangci-lint..."
          go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
        else
          echo "golangci-lint already installed"
        fi

        # Install gofumpt
        if ! command -v gofumpt &> /dev/null; then
          echo "Installing gofumpt..."
          go install mvdan.cc/gofumpt@latest
        else
          echo "gofumpt already installed"
        fi

        # Install gosec
        if ! command -v gosec &> /dev/null; then
          echo "Installing gosec..."
          go install github.com/securecodewarrior/gosec/v2/cmd/gosec@latest
        else
          echo "gosec already installed"
        fi

        echo "✅ Development tools installed!"

  security-scan:
    desc: Run security scanning
    summary: |
      Run security vulnerability scanning
    cmds:
      - echo "Running security scan..."
      - |
        if command -v gosec >/dev/null 2>&1; then
          gosec ./...
        else
          echo "gosec not found, skipping security scan"
        fi

  install-goreleaser:
    desc: Install GoReleaser
    summary: |
      Install GoReleaser for release management
    cmds:
      - |
        if ! command -v goreleaser &> /dev/null; then
          echo "Installing GoReleaser..."
          go install github.com/goreleaser/goreleaser/v2@latest
        else
          echo "GoReleaser already installed: $(goreleaser --version)"
        fi

  check-release:
    desc: Validate GoReleaser configuration
    summary: |
      Check .goreleaser.yml configuration for errors
    cmds:
      - goreleaser check
    preconditions:
      - sh: command -v goreleaser
        msg: "GoReleaser not found. Install with: task install-goreleaser"

  snapshot:
    desc: Build snapshot release (test release process)
    summary: |
      Build binaries for all platforms without publishing.
      Useful for testing the release process locally.
    deps:
      - generate-completion
    cmds:
      - echo "Building snapshot release..."
      - goreleaser release --snapshot --clean --skip=publish
      - echo "✅ Snapshot built in dist/"
      - ls -la dist/
    preconditions:
      - sh: command -v goreleaser
        msg: "GoReleaser not found. Install with: task install-goreleaser"

  release:
    desc: Create production release with GoReleaser
    summary: |
      Build and release binaries for all platforms using GoReleaser.
      This should be run on tag creation (CI handles this automatically).

      Requires: GITHUB_TOKEN environment variable
    deps:
      - generate-completion
    cmds:
      - echo "Running GoReleaser release..."
      - goreleaser release --clean
    preconditions:
      - sh: command -v goreleaser
        msg: "GoReleaser not found. Install with: task install-goreleaser"
      - sh: test -n "$GITHUB_TOKEN"
        msg: "GITHUB_TOKEN environment variable required for releases"

  generate-completion:
    desc: Generate shell completion scripts for GoReleaser
    summary: |
      Generate auto-completion scripts for bash, zsh, and fish.
      Required before running GoReleaser release/snapshot.
    deps:
      - build
    cmds:
      - echo "Generating shell completion scripts..."
      - |
        mkdir -p dist/completion

        # urfave/cli/v3 may not support --completion flags
        # Create placeholder completion files for now
        # TODO: Implement proper completion scripts

        touch dist/completion/cr-api.bash
        touch dist/completion/cr-api.zsh
        touch dist/completion/cr-api.fish

        echo "✅ Completion placeholders created in dist/completion/"
        echo "TODO: Implement actual shell completions"

  help:
    desc: Show API usage examples (Go CLI)
    summary: |
      Display detailed usage examples for the Go CLI, including prerequisites and common commands.
    cmds:
      - echo "Clash Royale API - Go CLI Usage Examples:"
      - echo "=========================================="
      - echo ''
      - echo "Prerequisites:"
      - 'echo "1. Build binaries: task build"'
      - 'echo "2. Set CLASH_ROYALE_API_TOKEN in .env file"'
      - 'echo "3. Set DEFAULT_PLAYER_TAG in .env to skip providing tag each time"'
      - 'echo "4. Install dev tools: task install-tools (optional, for linting)"'
      - echo ''
      - echo "Basic Player Operations:"
      - 'echo "1. Basic player analysis: task run -- #PLAYER_TAG"'
      - 'echo "2. Save results: task run-with-save -- #PLAYER_TAG"'
      - 'echo "3. Export to CSV: task export-csv -- #PLAYER_TAG"'
      - 'echo "4. Export all data: task export-all -- #PLAYER_TAG"'
      - echo ''
      - echo "Export Operations:"
      - 'echo "5. Export player profile: task export-player -- #PLAYER_TAG"'
      - 'echo "6. Export card analysis: task export-analysis -- #PLAYER_TAG"'
      - 'echo "7. Export battle log: task export-battles -- #PLAYER_TAG"'
      - 'echo "8. Export event data: task export-events-csv -- #PLAYER_TAG"'
      - 'echo "9. Export everything: task export-player-all -- #PLAYER_TAG"'
      - echo ''
      - echo "Deck Operations:"
      - 'echo "10. Build optimized deck: task build-deck -- #PLAYER_TAG"'
      - 'echo "11. Build war deck lineup: task war-decks -- #PLAYER_TAG"'
      - 'echo "12. Optimize existing deck: task deck-optimize -- #PLAYER_TAG"'
      - 'echo "13. Find budget decks: task deck-budget -- #PLAYER_TAG"'
      - echo ''
      - echo "Event Deck Operations:"
      - 'echo "14. Scan for event decks: task scan-events -- #PLAYER_TAG"'
      - 'echo "15. Export event decks: task export-events -- #PLAYER_TAG"'
      - 'echo "16. Export deck builder format: task export-decks -- #PLAYER_TAG"'
      - 'echo "17. Analyze events: task analyze-events -- #PLAYER_TAG"'
      - 'echo "18. Sync recent events: task sync-events -- #PLAYER_TAG"'
      - echo ''
      - echo "Archetype Analysis:"
      - 'echo "19. Analyze archetypes: task analyze-archetypes -- #PLAYER_TAG"'
      - 'echo "20. Export archetypes: task export-archetypes -- #PLAYER_TAG"'
      - echo ''
      - echo "Evolution & Upgrade Analysis:"
      - 'echo "21. Recommend evolutions: task evolution-recommend -- #PLAYER_TAG"'
      - 'echo "22. Analyze upgrade impact: task upgrade-impact -- #PLAYER_TAG"'
      - 'echo "23. Simulate upgrades: task what-if -- Knight:14 Archers:13"'
      - 'echo "24. Analyze playstyle: task playstyle -- #PLAYER_TAG"'
      - echo ''
      - echo "Development Commands:"
      - 'echo "- Build: task build"'
      - 'echo "- Test: task test"'
      - 'echo "- Lint: task lint (includes golangci-lint)"'
      - 'echo "- Format: task format"'
      - 'echo "- Security scan: task security-scan"'
      - echo ''
      - echo "Release/CI Commands:"
      - 'echo "- Build snapshot: task snapshot"'
      - 'echo "- Generate shell completion: task generate-completion"'
      - 'echo "- Install dev tools: task install-tools"'
      - echo ''
      - 'echo "Replace #PLAYER_TAG with actual tag (e.g., '#PLAYERTAG')"'
      - 'echo "Or set DEFAULT_PLAYER_TAG in .env and omit -- #PLAYER_TAG from commands"'