5.3 KiB
5.3 KiB
✨ AWESOME ✨
A next-level ground-breaking full-featured CLI application for exploring and curating awesome lists from GitHub
🎯 Features
Core Features
- 🌟 Browse Awesome Lists - Navigate through thousands of curated awesome lists from sindresorhus/awesome
- 🔍 Full-Text Search - Lightning-fast SQLite FTS5 powered search across all indexed READMEs
- 📚 Interactive Shell - Powerful shell with search completion and history
- 🎲 Random Discovery - Serendipitously discover random projects from the index
- 📖 Beautiful README Viewer - Styled markdown rendering in your terminal
Organization & Curation
- ⭐ Smart Bookmarks - Save favorites with tags, categories, and notes
- 📝 Custom Lists - Create your own awesome lists with beautiful styling
- 🎨 Export Options - Export to Markdown, PDF, EPUB, and other ebook formats
- 🏷️ Auto-Tagging - Automatic extraction of tags and categories from content
- ✍️ Annotations - Add notes to entire documents or specific lines
Intelligence & Insights
- 📊 Statistics Dashboard - Comprehensive stats about your index
- 📈 GitHub Integration - Stars, forks, last commit, and more
- 🔄 Smart Updates - Update bookmarked READMEs with diff preview
- 📜 Reading History - Track what you've explored
- 🎯 Auto-Complete - Intelligent completion for tags and categories
Developer Features
- 🚀 Git Integration - Clone repositories directly from the app
- 🔧 Recursive Indexing - Deep crawl of awesome lists hierarchy
- 🎭 Background Operations - Fancy loaders for all async operations
- 🐛 Debug Mode - Accessible via Node.js debug port
- ⚙️ Configurable - Extensive settings via CLI
🎨 Theme
Beautiful purple, pink, and gold gradient color scheme throughout the entire application for a funky, cool, and awesome experience!
📦 Installation
cd /home/valknar/Projects/node.js/awesome
pnpm install
pnpm rebuild better-sqlite3
chmod +x awesome
⚡ GitHub Rate Limits - SOLVED with OAuth! 🔐
GitHub API has strict rate limits:
- Without auth: 60 requests/hour ⏰
- With OAuth: 5,000 requests/hour 🚀 (83x more!)
🎉 Super Easy OAuth Setup (30 seconds!):
./awesome settings
→ GitHub Authentication
→ OAuth (Recommended)
→ Browser opens, enter code, done! ✨
That's it! No manual token creation, no copy-pasting!
Features:
- ✅ Browser auto-opens to GitHub auth page
- ✅ Just enter the code shown in terminal
- ✅ Click authorize and you're done!
- ✅ 83x more API requests instantly
- ✅ Secure - token stored locally
- ✅ Fallback - manual token still available
When you hit rate limits (rare with OAuth), you get options:
- ⏭️ Skip remaining items
- ⏰ Wait and continue
- ❌ Abort
See OAUTH_SETUP.md for complete guide!
🚀 Usage
Interactive Mode
./awesome
Commands
# Build the index (run this first!)
./awesome index
# Search
./awesome search "react hooks"
# Interactive shell
./awesome shell
# Browse lists
./awesome browse
# Random README
./awesome random
# Manage bookmarks
./awesome bookmarks
# Manage custom lists
./awesome lists
# View history
./awesome history
# Statistics
./awesome stats
# Settings
./awesome settings
# Clone a repository
./awesome checkout owner/repo
# Debug mode
node --inspect=9230 awesome
🗄️ Database Schema
The application uses SQLite3 with FTS5 for full-text search. Data is stored in ~/.awesome/awesome.db.
Tables
- awesome_lists - Indexed awesome lists (hierarchical)
- repositories - Individual projects with GitHub stats
- readmes - README content with versions
- readmes_fts - Full-text search index
- bookmarks - User bookmarks with tags/categories
- custom_lists - User-created awesome lists
- custom_list_items - Items in custom lists
- reading_history - Reading activity tracking
- annotations - Document and line annotations
- tags - Extracted and user-defined tags
- categories - Extracted and user-defined categories
- settings - Application configuration
- readme_versions - Version history for diffs
🎯 Workflow
- First Run:
./awesome index- Recursively crawls and indexes awesome lists - Explore: Search, browse, discover random projects
- Organize: Bookmark favorites, add tags and categories
- Curate: Create custom awesome lists
- Share: Export your lists in multiple formats
- Update: Keep your index fresh with smart diff-based updates
🛠️ Technology Stack
- Node.js 22+ - Modern JavaScript runtime
- SQLite3 + FTS5 - Fast, embedded database with full-text search
- Inquirer.js - Beautiful interactive prompts
- Chalk & Gradient-String - Colorful terminal output
- Marked & Marked-Terminal - Markdown rendering
- Simple-Git - Git operations
- Axios - HTTP client for GitHub API
- Commander.js - CLI framework
- Ora & Nanospinner - Loading animations
- pnpm - Fast, efficient package manager
📝 License
MIT
🌟 Credits
Inspired by sindresorhus/awesome - the awesome list of awesome lists!
Made with 💜 and lots of ✨