first commit

.env.example

@@ -0,0 +1,19 @@
+# .env - Environment Configuration for poster-bash
+# Copy this file to .env and fill in your values
+
+# IGDB API Credentials
+# Get your credentials from: https://api-docs.igdb.com/#account-creation
+IGDB_CLIENT_ID="your_client_id_here"
+IGDB_CLIENT_SECRET="your_client_secret_here"
+
+# Scan Directories
+# SCAN_DIR: Directory to scan in normal mode
+# TEST_DIR: Directory to scan in test mode (--test-run)
+
+SCAN_DIR="/media/Games"
+TEST_DIR="/test-games"
+
+# Optional: Override default settings
+# PROGRESS_MODE="both"
+# LOG_LEVEL="info"
+# RETRY_COUNT=3

.gitignore

@@ -0,0 +1,10 @@
+# Credentials ve sensitive dosyalar
+.env
+*.conf
+*.log
+
+# IgDB tokens ve cache
+.token-cache
+
+# Test dosyaları
+*.tmp

DESIGN.md

@@ -0,0 +1,824 @@
+# 🏗️ POSTER-BASH - MİMARİ TASARIM BELGESİ v1.0
+
+## Doküman Versiyonu
+- **Versiyon**: 1.0
+- **Tarih**: 2025-02-04
+- **Durum**: Taslak (Onay Bekliyor)
+
+---
+
+## 1. SİSTEM GENEL BAKIŞ
+
+### 1.1 Mimari Tarz
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     POSTER-BASH SYSTEM                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
+│  │   SCANNER   │───▶│    IGDB     │───▶│ DOWNLOADER  │          │
+│  │  Module     │    │   Module    │    │   Module    │          │
+│  └─────────────┘    └─────────────┘    └─────────────┘          │
+│         │                   │                   │                │
+│         ▼                   ▼                   ▼                │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
+│  │     UI      │    │   CONFIG    │    │    LOG      │          │
+│  │   Module    │    │   Module    │    │  Module     │          │
+│  └─────────────┘    └─────────────┘    └─────────────┘          │
+│                                                                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 1.2 Teknoloji Yığını
+| Katman | Teknoloji | Açıklama |
+|--------|-----------|----------|
+| **Script** | Bash 4.0+ | POSIX uyumlu |
+| **HTTP Client** | curl | API istekleri |
+| **JSON Parser** | jq | JSON işleme |
+| **ASCII Art** | figlet/toilet | 3D logo |
+| **Colors** | ANSI Escape Codes | Renkli terminal |
+| **Config** | bash variable export | Ayar yönetimi |
+
+---
+
+## 2. MODÜLER MİMARİ
+
+### 2.1 Modül Hiyerarşisi
+```
+poster-bash (Main Entry Point)
+│
+├── lib/core.sh              # Core utilities & shared functions
+├── lib/config.sh            # Config management
+├── lib/logger.sh            # Logging system
+├── lib/ui.sh                # Terminal UI & colors
+├── lib/scanner.sh           # Directory & ISO scanner
+├── lib/igdb.sh              # IGDB API integration
+├── lib/downloader.sh        # Poster download & retry logic
+└── lib/auth.sh              # OAuth token management
+```
+
+### 2.2 Modül Sorumlulukları
+
+#### 2.2.1 Main Entry Point (`poster-bash`)
+```bash
+Sorumluluklar:
+- Başlangıç kontrolü (dependencies, config)
+- 3D logo gösterimi
+- Ana iş akışı koordinasyonu
+- Hata yakalama ve graceful exit
+
+Interface:
+main() → init → scan → process → download → report → cleanup
+```
+
+#### 2.2.2 Core Module (`lib/core.sh`)
+```bash
+Sorumluluklar:
+- Global değişken tanımları
+- Shared utility functions
+- Error codes ve exit handling
+- Network connectivity check
+
+Public Functions:
+- check_dependencies()
+- check_internet()
+- exit_with_code()
+- sanitize_filename()
+
+Exported Variables:
+- SCRIPT_VERSION="1.0.0"
+- RETRY_MAX=3
+- TIMEOUT_SECONDS=30
+```
+
+#### 2.2.3 Config Module (`lib/config.sh`)
+```bash
+Sorumluluklar:
+- Config dosyası okuma/yazma
+- Environment variable loading
+- Validation ve defaults
+
+Public Functions:
+- config_load()
+- config_save()
+- config_get(key)
+- config_set(key, value)
+
+Config Structure:
+~/.game-bash.conf:
+  IGDB_CLIENT_ID="..."
+  IGDB_CLIENT_SECRET="..."
+  IGDB_ACCESS_TOKEN=""       # Auto-filled
+  IGDB_TOKEN_EXPIRES=""      # Auto-filled
+  PROGRESS_MODE="both"
+  LOG_LEVEL="info"
+  RETRY_COUNT=3
+```
+
+#### 2.2.4 Logger Module (`lib/logger.sh`)
+```bash
+Sorumluluklar:
+- Log dosyasına yazma
+- Terminal çıktısı formatlama
+- Log level filtering
+
+Public Functions:
+- log_info(message)
+- log_warn(message)
+- log_error(message)
+- log_success(message)
+
+Log Format:
+[YYYY-MM-DD HH:MM:SS] LEVEL Message
+
+Output:
+- Terminal: Colored output
+- File: ~/.game-bash.log
+```
+
+#### 2.2.5 UI Module (`lib/ui.sh`)
+```bash
+Sorumluluklar:
+- ANSI renk yönetimi
+- 3D ASCII logo gösterimi
+- Progress bar çizimi
+- Retro efektler
+
+Public Functions:
+- ui_show_logo()
+- ui_print_header(text)
+- ui_show_progress(current, total, text)
+- ui_color_print(color, text)
+
+Colors:
+- RED: Errors
+- GREEN: Success
+- YELLOW: Warnings
+- BLUE: Info
+- MAGENTA: Headers
+- CYAN: Progress
+
+3D Logo:
+- Font: "standard" (figlet) or "future" (toilet)
+- Color: Cyan with bold
+```
+
+#### 2.2.6 Scanner Module (`lib/scanner.sh`)
+```bash
+Sorumluluklar:
+- Recursive directory scanning
+- .iso dosyası tespiti
+- Oyun adı çıkarımı
+
+Public Functions:
+- scanner_scan_directory(path)
+- scanner_find_iso(directory)
+- scanner_extract_game_name(iso_path)
+
+Data Structure:
+ISO Entry:
+{
+  path: "/full/path/to/game.iso",
+  directory: "/full/path/to",
+  name: "Game Name",
+  has_poster: false
+}
+
+Return: Array of ISO entries (space-separated)
+```
+
+#### 2.2.7 IGDB Module (`lib/igdb.sh`)
+```bash
+Sorumluluklar:
+- OAuth token yönetimi
+- Oyun arama
+- Cover URL retrieval
+
+Public Functions:
+- igdb_authenticate()              # Get/refresh token
+- igdb_search_game(name)           # Search by name
+- igdb_search_with_vr(name)        # Search with VR suffix
+- igdb_get_cover_url(game_id)      # Get cover image URL
+
+API Endpoints:
+POST https://id.twitch.tv/oauth2/token
+  Request:  {"client_id":"...", "client_secret":"...", "grant_type":"client_credentials"}
+  Response: {"access_token":"...", "expires_in":5045603, "token_type":"bearer"}
+
+POST https://api.igdb.com/v4/games
+  Headers:  {"Authorization":"Bearer ${token}", "Client-ID":"${client_id}"}
+  Body:     search "${name}"; fields name,cover;
+  Response: [{"id":123, "name":"Game", "cover":456}]
+
+POST https://api.igdb.com/v4/covers
+  Headers:  {"Authorization":"Bearer ${token}", "Client-ID":"${client_id}"}
+  Body:     fields url,image_id; where id=${cover_id};
+  Response: [{"id":456, "image_id":"abc123", "url":"..."}]
+
+Image URL: https://images.igdb.com/igdb/image/upload/t_cover_big/${image_id}.jpg
+```
+
+#### 2.2.8 Downloader Module (`lib/downloader.sh`)
+```bash
+Sorumluluklar:
+- Poster indirme
+- Retry logic
+- Dosya kaydetme
+
+Public Functions:
+- downloader_download_poster(url, output_path)
+- downloader_retry_with_backoff(url, output_path, max_retries)
+- downloader_check_if_exists(output_path)
+
+Flow:
+1. Check if poster.png exists → Skip if true
+2. Download with curl
+3. Validate file size (> 0)
+4. On failure: Retry with exponential backoff (1s, 2s, 4s)
+5. After max retries: Log and skip
+```
+
+#### 2.2.9 Auth Module (`lib/auth.sh`)
+```bash
+Sorumluluklar:
+- Token lifecycle management
+- Token refresh logic
+- Token validation
+
+Public Functions:
+- auth_get_token()              # Returns valid token (refresh if needed)
+- auth_is_expired()             # Check if token expired
+- auth_refresh()                # Refresh from API
+- auth_save_token()             # Save to config
+
+Token Flow:
+1. Check config for cached token
+2. Check expiration
+3. If expired or missing → refresh
+4. Save new token to config
+```
+
+---
+
+## 3. VERİ AKIŞI
+
+### 3.1 Ana Akış Diyagramı
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        START                                        │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  INITIALIZATION                                                     │
+│  ├─ Check dependencies (curl, jq, figlet)                          │
+│  ├─ Load config from ~/.game-bash.conf                            │
+│  ├─ Check internet connectivity                                    │
+│  ├─ Initialize logger                                              │
+│  └─ Show 3D logo                                                   │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  AUTHENTICATION                                                     │
+│  ├─ Check cached token                                             │
+│  ├─ Validate expiration                                            │
+│  └─ Refresh if needed                                              │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  SCANNING                                                           │
+│  ├─ Scan current directory recursively                             │
+│  ├─ Find all .iso files                                            │
+│  ├─ Extract game names                                             │
+│  └─ Build processing list                                          │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  PROCESSING LOOP (for each ISO)                                    │
+│  ├─ Show progress: [1/15] Game Name                               │
+│  ├─ Check if poster.png exists → Skip if yes                       │
+│  ├─ Search IGDB for game                                           │
+│  ├─ Not found? → Retry with " VR" suffix                           │
+│  ├─ Get cover URL from IGDB                                        │
+│  ├─ Download poster with retry (3x)                                │
+│  └─ Log result (success/fail)                                      │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  REPORT                                                             │
+│  ├─ Show summary                                                   │
+│  │   ├─ Total games found                                          │
+│  │   ├─ Posters downloaded                                         │
+│  │   ├─ Skipped (already had poster)                               │
+│  │   └─ Failed                                                     │
+│  └─ Final message                                                  │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                        END                                          │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 Detaylı Akış (Oyun İşleme)
+```
+For each ISO file:
+┌──────────────────────────────────────────────────────────────────┐
+│ scanner_find_iso() → Returns: /path/to/Game/Game.iso            │
+└──────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ scanner_extract_game_name() → Returns: "Game"                   │
+└──────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ downloader_check_if_exists("/path/to/Game/poster.png")          │
+│   ├─ Exists? → Skip, log "Already has poster"                   │
+│   └─ Not exists? → Continue                                      │
+└──────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ igdb_search_game("Game")                                         │
+│   ├─ Found? → Get cover_id                                       │
+│   └─ Not found? → igdb_search_game("Game VR")                    │
+└──────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ igdb_get_cover_url(cover_id)                                     │
+│   ├─ Returns: https://images.igdb.com/.../image_id.jpg          │
+│   └─ Not found? → Log "No cover available", skip                 │
+└──────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ downloader_retry_with_backoff(url, "/path/to/Game/poster.png", 3)│
+│   ├─ Try 1: curl download                                        │
+│   ├─ Fail? → Wait 1s → Try 2                                    │
+│   ├─ Fail? → Wait 2s → Try 3                                    │
+│   ├─ Fail? → Wait 4s → Try 4                                    │
+│   └─ All fail? → Log error, skip                                 │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. API ENTEGRASYON DETAYLARI
+
+### 4.1 IGDB API Spesifikasyonu
+
+#### 4.1.1 OAuth Token Request
+```bash
+# Endpoint
+POST https://id.twitch.tv/oauth2/token
+
+# Request Parameters (application/x-www-form-urlencoded)
+client_id=buyzvv6qoyzj7rmauwkfom79h7fvpx
+client_secret=tivj7d6b21vqybpb4fx1oe85nffibt
+grant_type=client_credentials
+
+# Expected Response (200 OK)
+{
+  "access_token": "eyJhbGciOiIXVCJ9...",
+  "expires_in": 5045603,
+  "token_type": "bearer"
+}
+
+# Error Response (400 Bad Request)
+{
+  "status": 400,
+  "message": "invalid client"
+}
+```
+
+#### 4.1.2 Games Search
+```bash
+# Endpoint
+POST https://api.igdb.com/v4/games
+
+# Headers
+Authorization: Bearer ${ACCESS_TOKEN}
+Client-ID: buyzvv6qoyzj7rmauwkfom79h7fvpx
+Accept: application/json
+
+# Request Body (APICalc query format)
+search "Cyberpunk 2077";
+fields name,cover;
+limit 1;
+
+# Expected Response (200 OK)
+[
+  {
+    "id": 10904,
+    "name": "Cyberpunk 2077",
+    "cover": 12345
+  }
+]
+
+# Empty Response (no results)
+[]
+```
+
+#### 4.1.3 Covers Query
+```bash
+# Endpoint
+POST https://api.igdb.com/v4/covers
+
+# Headers (same as games)
+Authorization: Bearer ${ACCESS_TOKEN}
+Client-ID: buyzvv6qoyzj7rmauwkfom79h7fvpx
+
+# Request Body
+fields url,image_id;
+where id = 12345;
+
+# Expected Response
+[
+  {
+    "id": 12345,
+    "image_id": "co1abc",
+    "url": "//images.igdb.com/igdb/image/upload/t_cover_big/co1abc.jpg"
+  }
+]
+
+# Final Image URL
+https://images.igdb.com/igdb/image/upload/t_cover_big/co1abc.jpg
+```
+
+### 4.2 Image Size Options
+| Size | URL Pattern | Dimensions | Use Case |
+|------|-------------|------------|----------|
+| cover_small | t_cover_small | 90x128 | Thumbnails |
+| cover_big | **t_cover_big** | 264x374 | **Default (our choice)** |
+| screenshot_med | t_screenshot_med | 569x320 | Not used |
+| screenshot_big | t_screenshot_big | 889x500 | Not used |
+
+### 4.3 Error Handling Strategy
+```bash
+HTTP Code | Action
+----------|--------------------------------------------------
+200       | Success, process response
+400       | Invalid request, check token
+401       | Unauthorized, refresh token
+403       | Forbidden, check client credentials
+404       | Not found (no games/covers), skip with warning
+429       | Rate limit, wait and retry
+500+      | Server error, retry with backoff
+```
+
+---
+
+## 5. VERİ YAPILARI
+
+### 5.1 ISO Entry Structure
+```bash
+# Bash array representation (space-separated)
+ISO_ENTRY_FORMAT="{path}|{directory}|{name}|{has_poster}"
+
+# Example
+"/path/to/Game/Game.iso|/path/to/Game|Game|0"
+
+# Access pattern
+IFS='|' read -r path directory name has_poster <<< "$entry"
+```
+
+### 5.2 Config Structure
+```bash
+# Key-value pairs in bash source file
+export IGDB_CLIENT_ID="buyzvv6qoyzj7rmauwkfom79h7fvpx"
+export IGDB_CLIENT_SECRET="tivj7d6b21vqybpb4fx1oe85nffibt"
+export IGDB_ACCESS_TOKEN=""
+export IGDB_TOKEN_EXPIRES=""
+export PROGRESS_MODE="both"
+export LOG_LEVEL="info"
+export RETRY_COUNT=3
+```
+
+### 5.3 Summary Statistics
+```bash
+# Runtime statistics (stored in variables)
+TOTAL_GAMES=0
+DOWNLOADED=0
+SKIPPED=0
+FAILED=0
+```
+
+---
+
+## 6. KULLANICI ARAYÜZÜ TASARIMI
+
+### 6.1 Terminal Düzeni
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    ╔═══════════════════╗                       │
+│                    ║   GAME POSTER    ║                       │
+│                    ╚═══════════════════╝                       │
+│                                                                │
+│  📂 Scanning: /home/user/Games                                 │
+│  🎮 Found: 15 ISO files                                        │
+│                                                                │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━     │
+│                                                                │
+│  [1/15] Cyberpunk 2077                    [██████░░░░] 40%     │
+│  ✓ Downloaded: poster.png                                     │
+│                                                                │
+│  [2/15] Elden Ring                        [████████░░] 53%     │
+│  ℹ Already has poster, skipping...                             │
+│                                                                │
+│  [3/15] Unknown Game                        [███░░░░░░] 20%    │
+│  ⚠ Game not found, retrying with VR suffix...                 │
+│  ⚠ Not found in IGDB                                          │
+│                                                                │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━     │
+│                                                                │
+│  📊 SUMMARY                                                    │
+│  ✓ Downloaded: 12                                              │
+│  ℹ Skipped: 2                                                  │
+│  ✗ Failed: 1                                                   │
+│                                                                │
+│  📝 Log saved to: ~/.game-bash.log                            │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### 6.2 Renk Paleti
+```bash
+# ANSI Color Codes
+COLOR_RESET='\033[0m'
+COLOR_RED='\033[0;31m'      # Errors
+COLOR_GREEN='\033[0;32m'    # Success
+COLOR_YELLOW='\033[0;33m'   # Warnings
+COLOR_BLUE='\033[0;34m'     # Info
+COLOR_MAGENTA='\033[0;35m'  # Headers
+COLOR_CYAN='\033[0;36m'     # Progress/Logo
+COLOR_BOLD='\033[1m'
+COLOR_DIM='\033[2m'
+
+# Usage
+echo -e "${COLOR_GREEN}✓ Success message${COLOR_RESET}"
+echo -e "${COLOR_RED}✗ Error message${COLOR_RESET}"
+```
+
+### 6.3 Progress Bar Implementation
+```bash
+show_progress_bar() {
+    local current=$1
+    local total=$2
+    local width=40
+    local percentage=$((current * 100 / total))
+    local filled=$((width * current / total))
+    local empty=$((width - filled))
+
+    printf "["
+    printf "%${filled}s" | tr ' ' '█'
+    printf "%${empty}s" | tr ' ' '░'
+    printf "] %d%%\r" "$percentage"
+}
+```
+
+---
+
+## 7. HATA YÖNETİMİ
+
+### 7.1 Exit Code Convention
+```bash
+EXIT_SUCCESS=0           # Normal exit
+EXIT_ERROR_GENERAL=1     # General error
+EXIT_ERROR_DEPS=2        # Missing dependencies
+EXIT_ERROR_NETWORK=3     # Network error
+EXIT_ERROR_AUTH=4        # Authentication failed
+EXIT_ERROR_CONFIG=5      # Config error
+EXIT_ERROR_API=6         # API error
+```
+
+### 7.2 Error Recovery Flow
+```
+Error Occurs
+      │
+      ▼
+Check Type
+      │
+      ├─ Network Error → Check internet → Exit if offline
+      ├─ Auth Error → Refresh token → Retry → Exit if fail
+      ├─ API Error → Log warning → Skip current game → Continue
+      ├─ Download Error → Retry (3x) → Log → Skip → Continue
+      └─ Config Error → Show message → Exit
+```
+
+### 7.3 Graceful Degradation
+```bash
+# Fallback behaviors
+figlet not found → Use simple echo with colors
+jq not found → Fatal error (required dependency)
+curl not found → Fatal error (required dependency)
+Token refresh fail → Exit with auth error
+Internet down → Exit with network error
+```
+
+---
+
+## 8. PERFORMANS VE SKALABİLİTE
+
+### 8.1 Performance Targets
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Startup time | < 2s | Logo + auth + scan |
+| Per-game processing | 1-3s | API call + download |
+| Memory usage | Minimal | Bash processes |
+| Concurrent games | 1 | Sequential processing |
+
+### 8.2 Optimization Strategies
+```bash
+1. Token Caching
+   - Store in config, reuse until expired
+   - Reduces auth overhead
+
+2. Skip Existing Posters
+   - Check file existence before API call
+   - Saves bandwidth and time
+
+3. Minimal Dependencies
+   - Only curl, jq, figlet required
+   - Fast startup, low overhead
+
+4. Sequential Processing
+   - No parallel processing (bash limitation)
+   - Better error handling
+```
+
+---
+
+## 9. GÜVENLİK
+
+### 9.1 Security Considerations
+```bash
+1. Credential Protection
+   - Config file: ~/.game-bash.conf (chmod 600)
+   - .gitignore: Prevent git commit
+   - Never log tokens/secrets
+
+2. Input Sanitization
+   - Escape game names before API call
+   - Validate paths before file operations
+
+3. File Operations
+   - Check file exists before overwrite
+   - Use safe temp directories
+
+4. Network Security
+   - HTTPS only for API calls
+   - Validate SSL certificates
+```
+
+### 9.2 File Permissions
+```bash
+# Config file
+chmod 600 ~/.game-bash.conf
+
+# Script
+chmod 755 poster-bash
+
+# Library files
+chmod 644 lib/*.sh
+```
+
+---
+
+## 10. TEST STRATEJİSİ
+
+### 10.1 Unit Test Coverage
+```bash
+# Test categories
+1. Config Tests
+   - Load valid config
+   - Handle missing config
+   - Save and reload
+
+2. Scanner Tests
+   - Find ISO files
+   - Extract game names
+   - Handle empty directories
+
+3. IGDB Tests
+   - Token refresh
+   - Game search
+   - Cover URL retrieval
+
+4. Downloader Tests
+   - Download success
+   - Retry logic
+   - File existence check
+
+5. Logger Tests
+   - All log levels
+   - File writing
+   - Terminal output
+```
+
+### 10.2 Integration Test Scenarios
+```bash
+1. End-to-End Flow
+   - Multiple games
+   - Mix of found/not found
+   - VR suffix retry
+
+2. Error Scenarios
+   - No internet
+   - Invalid credentials
+   - API rate limit
+
+3. Edge Cases
+   - Special characters in game names
+   - Very long directory names
+   - Permission denied
+```
+
+---
+
+## 11. DEPLOYMENT
+
+### 11.1 Installation
+```bash
+# Clone or download
+git clone https://github.com/user/poster-bash.git
+cd poster-bash
+
+# Make executable
+chmod +x poster-bash
+
+# Copy to PATH (optional)
+sudo cp poster-bash /usr/local/bin/
+
+# First run (creates config)
+./poster-bash
+```
+
+### 11.2 Directory Structure After Install
+```
+~/.game-bash.conf          # User config
+~/.game-bash.log           # Log file
+/usr/local/bin/poster-bash # Executable (if installed)
+```
+
+---
+
+## 12. BAKIM VE EVRİM
+
+### 12.1 Version Strategy
+```
+Semantic Versioning: MAJOR.MINOR.PATCH
+
+- MAJOR: Breaking changes
+- MINOR: New features (backward compatible)
+- PATCH: Bug fixes
+
+Current: v1.0.0
+```
+
+### 12.2 Future Enhancements
+```
+Planned Features:
+- [ ] Parallel processing (background jobs)
+- [ ] Custom poster size selection
+- [ ] Multiple image sources fallback
+- [ ] Interactive mode (select games manually)
+- [ ] Database cache for faster lookups
+- [ ] GUI mode (optional)
+```
+
+---
+
+## 13. REFERANSLAR
+
+### 13.1 External Documentation
+- [IGDB API Documentation](https://api-docs.igdb.com/)
+- [Twitch OAuth Documentation](https://dev.twitch.tv/docs/authentication/)
+- [Bash Style Guide](https://google.github.io/styleguide/shellguide.html)
+
+### 13.2 Related Documents
+- `REQUIREMENTS.md` - Functional requirements
+- `README.md` - User documentation (to be created)
+- `CHANGELOG.md` - Version history (to be created)
+
+---
+
+## 14. ONAY KONTROL LİSTESİ
+
+- [x] Modüler yapı tanımlandı
+- [x] API entegrasyonu tasarlandı
+- [x] Veri akışı diagramı oluşturuldu
+- [x] Hata yönetimi stratejisi belirlendi
+- [x] Güvenlik önlemleri tanımlandı
+- [x] UI/UX tasarımı tamamlandı
+- [ ] Implementasyon onayı bekliyor
+- [ ] Kodlama aşamasına hazır
+
+---
+
+_v1.0 - 2025-02-04 | Tasarım Onayı Bekliyor_

README.md

@@ -0,0 +1,225 @@
+# 🎮 POSTER-BASH
+
+Linux için bash tabanlı terminal uygulaması. Oyun .iso dosyalarınızı tarar, IGDB API'den poster resimlerini bulur ve indirir.
+
+## 📋 Özellikler
+
+- ✅ **Otomatik Kurulum**: Eksik paketleri otomatik indirir ve kurar
+- ✅ **Otomatik Tarama**: Config'den belirtilen dizini tarar
+- ✅ **IGDB Entegrasyonu**: Dünyanın en büyük oyun veritabanından poster arar
+- ✅ **VR Desteği**: Oyun bulunamazsa otomatik olarak "VR" ile tekrar dener
+- ✅ **Akıllı Önbellek**: Zaten indirilen posterleri atlar
+- ✅ **Retries**: İndirme başarısız olursa 3 kere dener
+- ✅ **Retro Terminal**: Renkli çıktı, 3D ASCII logo, progress bar
+- ✅ **Detaylı Loglama**: Tüm işlemleri log dosyasına kaydeder
+- ✅ **Test Modu**: `--test-run` ile test dizininde eski posterleri temizleyip yenilerini indirir
+
+## 📸 Ekran Görüntüsü
+
+```
+    ╔═══════════════════╗
+    ║   GAME POSTER    ║
+    ╚═══════════════════╝
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+INFO Taranan dizin: /media/Games
+INFO Bulunan ISO dosyası sayısı: 5
+
+[1/5] Elden Ring            [████░░░░░] 20%
+✓ İndirildi: poster.png
+
+[2/5] Cyberpunk 2077        [█████░░░░] 40%
+ℹ Poster zaten var, atlanıyor...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 ÖZET
+✓ İndirildi: 2
+ℹ Atlandı: 2
+✗ Başarısız: 1
+```
+
+## 🚀 Kurulum
+
+### Tek Dosya
+
+```bash
+# Script'i indirin
+wget https://raw.githubusercontent.com/wisecolt/poster-bash/main/poster-bash
+
+# Çalıştırılabilir yapın
+chmod +x poster-bash
+```
+
+### Ayarlama (.env)
+
+Script ile aynı dizine `.env` dosyası oluşturun:
+
+```bash
+# .env
+IGDB_CLIENT_ID=your_client_id_here
+IGDB_CLIENT_SECRET=your_client_secret_here
+
+SCAN_DIR="/media/Games"
+TEST_DIR="/test-games"
+```
+
+**Not**: IGDB credentials almak için: https://api-docs.igdb.com/#account-creation
+
+### Kullanıma Hazır Kılma
+
+```bash
+# Script'i oyunlarınızın olduğu dizine koyun
+cp poster-bash /media/Games/
+
+# .env dosyasını aynı dizine oluşturun
+cd /media/Games
+nano .env    # yukarıdaki içerikle doldurun
+
+# Çalıştırın
+./poster-bash
+```
+
+**İlk çalıştırmada script otomatik olarak şunları yapar:**
+- `curl` ve `jq` paketlerini kurar (sudo ile)
+- Config dosyasını oluşturur (`~/.game-bash.conf`)
+- İlk poster indirmelerini yapar
+
+## 📖 Kullanım
+
+### Temel Kullanım
+
+```bash
+# Normal mod - SCAN_DIR'yi tarar
+./poster-bash
+
+# Test modu - TEST_DIR'yi tarar, eski posterleri temizler
+./poster-bash --test-run
+```
+
+### Seçenekler
+
+```bash
+poster-bash [SEÇENEKLER]
+
+Seçenekler:
+  -h, --help        Yardım mesajını gösterir
+  -v, --version     Versiyon bilgisini gösterir
+  -c, --config      Config dosyasının konumunu gösterir
+  -l, --log         Log dosyasını gösterir
+  --clear-log       Log dosyasını temizler
+  --test-run        Test modunda çalışır (önce eski posterleri temizler)
+```
+
+### Örnekler
+
+```bash
+# Yardım
+./poster-bash --help
+
+# Versiyon
+./poster-bash --version
+
+# Logları görüntüle
+./poster-bash --log
+
+# Config dosyasını görüntüle
+./poster-bash --config
+```
+
+## ⚙️ Yapılandırma
+
+Script iki yerden ayar okur:
+
+### 1. .env Dosyası (Proje Dizini)
+
+```bash
+# .env
+IGDB_CLIENT_ID=your_client_id
+IGDB_CLIENT_SECRET=your_client_secret
+SCAN_DIR="/path/to/games"
+TEST_DIR="/test-games"
+```
+
+### 2. Config Dosyası (Otomatik Oluşturulur: `~/.game-bash.conf`)
+
+Config dosyası IGDB token'ını ve diğer ayarları saklar.
+
+---
+
+## 📁 Dizin Yapısı
+
+```
+/media/Games/
+├── poster-bash          # Script (tek dosya)
+├── .env                 # Ayarlarınız
+├── Elden Ring/
+│   ├── Elden Ring.iso
+│   └── poster.png       # Script indirir
+├── Cyberpunk 2077/
+│   ├── Cyberpunk 2077.iso
+│   └── poster.png       # Script indirir
+└── ... (diğer oyunlar)
+```
+
+## 🔄 Nasıl Çalışır?
+
+1. **Başlat**: Script çalıştırılır
+2. **Otomatik Kurulum**: Eksik paketler (`curl`, `jq`) otomatik kurulur
+3. **.env Okuma**: Ayarlar aynı dizindeki `.env` dosyasından okunur
+4. **Tarama**: Config'deki dizin taranır
+5. **IGDB Arama**: Oyunlar IGDB'de aranır
+6. **VR Yeniden Deneme**: Bulunamazsa "VR" eklenip tekrar aranır
+7. **Poster İndirme**: Bulunursa poster indirilir
+8. **Kaydet**: `poster.png` olarak oyun dizinine kaydedilir
+
+## 🐛 Sorun Giderme
+
+### "sudo: ./poster-bash: command not found"
+
+```bash
+# Tam path ile çalıştırın
+bash /path/to/poster-bash
+
+# Veya sistem bin dizinine kopyalayın
+sudo cp /path/to/poster-bash /usr/local/bin/
+sudo poster-bash --test-run
+```
+
+### "Permission denied" hatası
+
+```bash
+# Script'e çalıştırma izni verin
+chmod +x poster-bash
+```
+
+### ".env dosyası bulunamadı"
+
+```bash
+# Script ile aynı dizinde .env oluşturun
+cat > .env << EOF
+IGDB_CLIENT_ID=your_id
+IGDB_CLIENT_SECRET=your_secret
+SCAN_DIR="/path/to/games"
+TEST_DIR="/test-games"
+EOF
+```
+
+## 📜 Lisans
+
+Bu proje MIT lisansı altında lisanslanmıştır.
+
+## 🙏 Teşekkürler
+
+- [IGDB](https://www.igdb.com) - Oyun veritabanı için
+- [Twitch](https://dev.twitch.tv) - OAuth için
+
+## 📞 İletişim
+
+- **GitHub**: [wisecolt/poster-bash](https://github.com/wisecolt/poster-bash)
+- **Issues**: [GitHub Issues](https://github.com/wisecolt/poster-bash/issues)
+
+---
+
+_v1.0.0 - 2025_

REQUIREMENTS.md

@@ -0,0 +1,210 @@
+# 📋 GAME POSTER - GEREKSİNİMLER BELGESİ v1.0
+
+## Proje Özeti
+Linux için bash tabanlı terminal uygulaması. Oyun .iso dosyalarını tespit edip IGDB API'den poster resimlerini indirir.
+
+---
+
+## 1. FONKSİYONEL GEREKSİNİMLER
+
+### FR-1: Dizin Tarama
+```
+FR-1.1: Script'in çalıştığı dizindeki alt klasörleri recursive olarak taramalıdır
+FR-1.2: Her klasörde .iso dosyası aramalıdır
+FR-1.3: .iso bulunan klasörleri işleme almalıdır
+FR-1.4: .iso bulunamayan klasörler için ".iso dosyası bulunamadı" mesajı vermeli ve atlamalıdır
+```
+
+### FR-2: Oyun Adı Çıkarımı
+```
+FR-2.1: .iso dosya adından oyun adını çıkarmalıdır
+FR-2.2: ".iso" uzantısını kaldırmalıdır
+FR-2.3: Örnek: "Cyberpunk 2077.iso" → "Cyberpunk 2077"
+```
+
+### FR-3: IGDB API Entegrasyonu
+```
+FR-3.1: IGDB API ile oyun aramalıdır
+FR-3.2: Client ID: 6174nc97wqqt2ny13fildjy5co52rg
+FR-3.3: OAuth redirect URI: http://localhost
+FR-3.4: Access token almak için OAuth flow implement edilmelidir (client credentials flow)
+FR-3.5: Oyun bulamazsa "[oyun_adı] VR" formatında yeniden aramalıdır
+FR-3.6: Birden fazla sonuç dönerse ilk sonucu kullanmalıdır
+FR-3.7: Access token'ı ~/.game-poster.conf'da cache'lemelidir
+```
+
+### FR-4: Poster İndirme
+```
+FR-4.1: IGDB'den poster URL'sini almalıdır
+FR-4.2: Poster'i PNG formatında indirmelidir
+FR-4.3: Dosya adı: poster.png
+FR-4.4: .iso ile aynı dizine kaydetmelidir
+FR-4.5: Aynı dizinde poster.png zaten varsa atlamalıdır
+FR-4.6: İndirme başarısız olursa 3 kere yeniden denemelidir
+FR-4.7: 3 deneme sonunda da başarısız olursa log'a yazmalıdır (dosya koyma)
+FR-4.8: Poster bulunamazsa hiçbir dosya koyma, sadece log tut
+```
+
+### FR-5: Progress Gösterimi
+```
+FR-5.1: Basamalı ilerleme göstermelidir: "[1/15] Cyberpunk 2077..."
+FR-5.2: Progress bar göstermelidir: "[████░░░░] 25%
+FR-5.3: Default mode: "both" (hem steps hem bar)
+```
+
+---
+
+## 2. NON-FONKSİYONEL GEREKSİNİMLER
+
+### NFR-1: Teknoloji Yığını
+```
+NFR-1.1: Bash script (sh/POSIX uyumlu)
+NFR-1.2: Minimum bağımlılık (curl, jq, figlet/toilet)
+NFR-1.3: Python/Yarn vs. gerektirmemelidir
+```
+
+### NFR-2: Terminal Arayüzü
+```
+NFR-2.1: Renkli çıktı (ANSI renk kodları)
+NFR-2.2: Başlangıçta "GAME POSTER" 3D ASCII logo (figlet/toilet)
+NFR-2.3: Retro/pixel tarzı görsel efektler
+NFR-2.4: Türkçe dil desteği
+```
+
+### NFR-3: Yapılandırma
+```
+NFR-3.1: Config dosyası: ~/.game-bash.conf
+NFR-3.2: Log dosyası: ~/.game-bash.log
+NFR-3.3: Access token'ı config'de cache'lemelidir
+```
+
+### NFR-4: Hata Yönetimi
+```
+NFR-4.1: İnternet bağlantısı yoksa hata verip çıkmalıdır
+NFR-4.2: IGDB API hatasında kullanıcıyı bilgilendirmelidir
+NFR-4.3: Her işlem için log tutmalıdır
+```
+
+---
+
+## 3. KULLANICI HİKAYELERİ
+
+| ID | Hikaye | Kabul Kriteri |
+|----|--------|---------------|
+| US-1 | Kullanıcı, oyun posterlerini otomatik indirmek istiyor | Script çalıştığında tüm oyunlar için poster indirilmeli |
+| US-2 | Kullanıcı, ilerleme durumunu görmek istiyor | Terminalde progress bar ve basamalı ilerleme gösterilmeli |
+| US-3 | Kullanıcı, zaten indirilmiş posterleri tekrar indirmek istemiyor | poster.png varsa atlanmalı |
+| US-4 | Kullanıcı, VR oyunları için de poster indirmek istiyor | Oyun bulunamazsa "VR" eklenip aranmalı |
+
+---
+
+## 4. TEKNİK SPESİFİKASYON
+
+### 4.1 Proje Yapısı
+```
+poster-bash/
+├── poster-bash               # Ana script (executable)
+├── lib/
+│   ├── igdb.sh               # IGDB API fonksiyonları
+│   ├── scanner.sh            # .iso tarama fonksiyonları
+│   ├── downloader.sh         # Poster indirme fonksiyonları
+│   └── ui.sh                 # Terminal UI fonksiyonları
+├── src/
+│   └── auth-setup.sh         # IGDB OAuth setup helper
+└── README.md                 # Kullanım dokümantasyonu
+```
+
+### 4.2 Config Dosyası Formatı
+```bash
+# ~/.game-bash.conf
+IGDB_CLIENT_ID="buyzvv6qoyzj7rmauwkfom79h7fvpx"
+IGDB_CLIENT_SECRET="tivj7d6b21vqybpb4fx1oe85nffibt"
+IGDB_REDIRECT_URI="http://localhost"
+IGDB_ACCESS_TOKEN=""          # Token cache (auto-filled)
+IGDB_TOKEN_EXPIRES=""         # Token expiration (auto-filled)
+PROGRESS_MODE="both"          # steps, bar, both
+LOG_LEVEL="info"
+RETRY_COUNT=3
+```
+
+### 4.3 IGDB API Endpoints
+```
+OAuth Token: https://id.twitch.tv/oauth2/token
+  - POST with: client_id, client_secret, grant_type=client_credentials
+
+Games Search: https://api.igdb.com/v4/games
+  - POST body: search "game name"; fields name,cover;
+
+Covers: https://api.igdb.com/v4/covers
+  - POST body: fields url,image_id; where id = X;
+  - Image URL: https://images.igdb.com/igdb/image/upload/t_cover_big/{image_id}.jpg
+```
+
+### 4.4 OAuth Flow (Client Credentials)
+```
+1. Kullanıcıdan IGDB Client Secret al
+2. POST https://id.twitch.tv/oauth2/token
+   - client_id: 6174nc97wqqt2ny13fildjy5co52rg
+   - client_secret: [kullanıcıdan alınan]
+   - grant_type: client_credentials
+3. Response: access_token, expires_in, token_type
+4. Token'ı config'e cache'le
+5. Token expired ise yenile
+```
+
+---
+
+## 5. KABUL TESTLERİ
+
+```
+AT-1: Script games dizininde çalıştırıldığında tüm klasörleri tarar
+AT-2: .iso dosyası "Cyberpunk 2077.iso" için "Cyberpunk 2077" aranır
+AT-3: IGDB'den poster bulunursa poster.png olarak kaydedilir
+AT-4: poster.png zaten varsa yeniden indirilmez
+AT-5: Oyun bulunamazsa "Oyun Adı VR" olarak yeniden aranır
+AT-6: Terminalde renkli çıktı ve 3D logo gösterilir
+AT-7: Log dosyasına tüm işlemler yazılır
+AT-8: İnternet yoksa hata verilip çıkılır
+AT-9: İndirme başarısız olursa 3 kere yeniden denenir
+```
+
+---
+
+## 6. LOG FORMATI
+
+```
+[2025-02-04 15:30:45] INFO  Starting poster-bash v1.0
+[2025-02-04 15:30:46] INFO  Scanning directory: /home/user/Games
+[2025-02-04 15:30:47] INFO  Found ISO: Cyberpunk 2077.iso
+[2025-02-04 15:30:48] INFO  Searching IGDB: "Cyberpunk 2077"
+[2025-02-04 15:30:49] INFO  Found game: Cyberpunk 2077 (ID: 10904)
+[2025-02-04 15:30:50] INFO  Downloading poster: https://images.igdb.com/...
+[2025-02-04 15:30:52] SUCCESS Poster saved: /home/user/Games/Cyberpunk 2077/poster.png
+[2025-02-04 15:30:53] WARN  Game not found: "Unknown Game"
+[2025-02-04 15:30:54] INFO  Retrying with VR suffix: "Unknown Game VR"
+[2025-02-04 15:30:55] ERROR Poster download failed: HTTP 404
+```
+
+---
+
+## 7. BİTİŞ KRİTERLERİ
+
+- [x] Gereksinimler belgesi tamamlandı
+- [x] OAuth flow planlandı
+- [ ] Mimari tasarım tamamlanacak (/sc:design)
+- [ ] Implementasyon tamamlanacak (/sc:implement)
+- [ ] Testler yazılacak
+- [ ] Dokümantasyon yazılacak
+
+---
+
+## 8. SONRAKİ ADIMLAR
+
+1. ✅ **Gereksinim Belgesi** (TAMAMLANDI)
+2. ⏭️ **Mimari Tasarım** → `/sc:design`
+3. ⏭️ **Implementasyon** → `/sc:implement`
+4. ⏭️ **Test & Dokümantasyon**
+
+---
+
+_v1.0 - 2025-02-04_