a new start

2025-10-25 15:52:06 +02:00
commit 700c73bcbf
28 changed files with 7295 additions and 0 deletions
--- a/RATE_LIMITS.md
+++ b/RATE_LIMITS.md
@@ -0,0 +1,140 @@
+# ⚡ GitHub Rate Limits - Solved!
+
+## The Problem
+
+GitHub API has strict rate limits:
+- **Without token**: 60 requests/hour
+- **With token**: 5000 requests/hour
+
+When indexing awesome lists, you can easily hit the limit!
+
+## The Solution
+
+We've implemented a smart rate limit handler that:
+
+### 1. **Gives You Options**
+When rate limit is hit, you can choose:
+- ⏰ Wait and continue (if you have time)
+- ⏭️ Skip remaining and continue with what you have
+- ❌ Abort the indexing
+
+### 2. **Supports GitHub Tokens**
+Add your Personal Access Token to get **83x more requests**!
+
+#### Quick Setup (2 minutes):
+
+1. **Generate Token**
+   - Go to: https://github.com/settings/tokens
+   - Click "Generate new token (classic)"
+   - Give it a name: "awesome-cli"
+   - Select scope: **`public_repo`** (read-only access to public repos)
+   - Click "Generate token"
+   - Copy the token (looks like: `ghp_xxxxxxxxxxxx`)
+
+2. **Add to Awesome**
+   ```bash
+   ./awesome settings
+   # Choose: Edit settings
+   # Paste your token when prompted
+   ```
+
+3. **Enjoy 5000 requests/hour!** ✨
+
+### 3. **Better UX**
+- Shows clear wait times in minutes, not seconds
+- Helpful tips when rate limit is hit
+- Only shows token reminder once per session
+- Clean error messages
+
+## Usage Tips
+
+### For Quick Exploration
+```bash
+# Index just a sample (10 lists)
+./awesome index
+# Choose: "Index a random sample"
+```
+
+### For Full Indexing
+```bash
+# Add your token first
+./awesome settings
+
+# Then index everything
+./awesome index
+# Choose: "Index everything"
+```
+
+### If You Hit the Limit
+When you see the rate limit message:
+
+**Option 1: Skip and Continue** (Recommended for first run)
+- You'll have partial data to explore
+- Can always index more later
+- No waiting!
+
+**Option 2: Wait**
+- Best if you're close to finishing
+- App will wait automatically
+- Can resume where it left off
+
+**Option 3: Abort**
+- Start over later with a token
+- Or try a smaller sample first
+
+## Rate Limit Math
+
+### Without Token (60/hour)
+- **1 awesome list** = ~1 request (fetch README)
+- **1 repository** = ~2 requests (repo info + README)
+- **Average awesome list** = ~50 repos = 100 requests
+- **Result**: Can index ~0.5 lists/hour
+
+### With Token (5000/hour)
+- **Result**: Can index ~50 lists/hour (100x faster!)
+
+## Best Practices
+
+1. **Start Small**
+   ```bash
+   ./awesome index → choose "sample"
+   ```
+
+2. **Add Token Before Big Index**
+   ```bash
+   ./awesome settings → add token
+   ./awesome index → choose "everything"
+   ```
+
+3. **Use Skip Option**
+   - If rate limited, choose "Skip"
+   - You'll still have data to explore!
+   - Can resume indexing later
+
+4. **Index Specific Categories**
+   ```bash
+   ./awesome index → choose "Select specific categories"
+   # Pick just what interests you
+   ```
+
+## Pro Tips
+
+💡 **Token is stored securely** in `~/.awesome/awesome.db` (SQLite)
+
+💡 **Token is displayed masked** as `***xxxx` in settings
+
+💡 **No network transmission** - token only used for GitHub API
+
+💡 **Read-only access** - `public_repo` scope can't modify anything
+
+💡 **Revoke anytime** at https://github.com/settings/tokens
+
+## Summary
+
+🎯 **Problem**: Rate limits block indexing
+✅ **Solution**: Smart handler + token support
+🚀 **Result**: 83x more requests, better UX!
+
+---
+
+**Stay awesome and never wait for rate limits again!** ✨