152 lines
6.3 KiB
Markdown
152 lines
6.3 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
AWESOME is a full-featured CLI application for exploring, curating, and managing awesome lists from GitHub. It provides an interactive terminal interface with search, bookmarking, custom list creation, and export capabilities.
|
||
|
|
|
||
|
|
## Core Technologies
|
||
|
|
|
||
|
|
- **Node.js 22+** - Required runtime
|
||
|
|
- **better-sqlite3** - Embedded database with FTS5 full-text search
|
||
|
|
- **commander.js** - CLI framework and command routing
|
||
|
|
- **inquirer.js** - Interactive prompts and menus
|
||
|
|
- **marked + marked-terminal** - Terminal markdown rendering
|
||
|
|
- **axios** - GitHub API client with OAuth support
|
||
|
|
|
||
|
|
## Commands
|
||
|
|
|
||
|
|
### Development
|
||
|
|
```bash
|
||
|
|
pnpm install # Install dependencies
|
||
|
|
pnpm rebuild better-sqlite3 # Rebuild native module
|
||
|
|
chmod +x awesome # Make executable
|
||
|
|
node awesome # Run application
|
||
|
|
node --inspect=9230 awesome # Debug mode
|
||
|
|
```
|
||
|
|
|
||
|
|
### Key Application Commands
|
||
|
|
```bash
|
||
|
|
./awesome # Interactive menu (default)
|
||
|
|
./awesome db # Download pre-built database from GitHub Actions
|
||
|
|
./awesome index # Build/rebuild index locally (first run required)
|
||
|
|
./awesome index -f # Force rebuild (clears data)
|
||
|
|
./awesome search "query" # Quick search
|
||
|
|
./awesome shell # Interactive shell
|
||
|
|
./awesome settings # Configure GitHub OAuth
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
### Entry Point
|
||
|
|
- `awesome` - Main executable that initializes database and sets up Commander routes
|
||
|
|
|
||
|
|
### Data Flow
|
||
|
|
1. **Indexing** (`lib/indexer.js`) - Fetches sindresorhus/awesome, recursively crawls awesome lists
|
||
|
|
2. **Storage** (`lib/database.js`) - Creates schema; (`lib/db-operations.js`) - CRUD operations
|
||
|
|
3. **Search** (`lib/search.js`) - FTS5 queries across indexed READMEs
|
||
|
|
4. **Display** (`lib/viewer.js`) - Markdown rendering with pagination
|
||
|
|
|
||
|
|
### Database Schema
|
||
|
|
Located at `~/.awesome/awesome.db` with these key tables:
|
||
|
|
- `awesome_lists` - Hierarchical list storage (with parent_id foreign key)
|
||
|
|
- `repositories` - Individual projects with GitHub metadata
|
||
|
|
- `readmes` - Full README content with version hashing
|
||
|
|
- `readmes_fts` - FTS5 virtual table for full-text search
|
||
|
|
- `bookmarks` - User favorites with tags/categories
|
||
|
|
- `custom_lists` + `custom_list_items` - User-curated lists
|
||
|
|
- `settings` - App configuration including GitHub tokens
|
||
|
|
|
||
|
|
### Module Responsibilities
|
||
|
|
|
||
|
|
**Core Operations:**
|
||
|
|
- `lib/database.js` - Schema creation, connection management, lifecycle
|
||
|
|
- `lib/db-operations.js` - All SQL queries and data operations
|
||
|
|
- `lib/github-api.js` - GitHub API wrapper with rate limiting
|
||
|
|
- `lib/github-oauth.js` - Device flow OAuth authentication
|
||
|
|
|
||
|
|
**Features:**
|
||
|
|
- `lib/indexer.js` - Recursive crawler for awesome lists, parses markdown links
|
||
|
|
- `lib/search.js` - FTS5 search interface with interactive result selection
|
||
|
|
- `lib/viewer.js` - Paginated README viewer with annotations
|
||
|
|
- `lib/bookmarks.js` - Bookmark management (add/remove/tag/export)
|
||
|
|
- `lib/custom-lists.js` - User list creation and export
|
||
|
|
- `lib/browser.js` - Hierarchical list navigation
|
||
|
|
- `lib/shell.js` - Command shell with history (~/.awesome/shell_history.txt)
|
||
|
|
- `lib/random.js` - Random README discovery
|
||
|
|
- `lib/history.js` - Reading activity tracking
|
||
|
|
- `lib/stats.js` - Index statistics dashboard
|
||
|
|
- `lib/checkout.js` - Git clone integration
|
||
|
|
- `lib/settings.js` - Configuration management
|
||
|
|
- `lib/db-download.js` - Download pre-built databases from GitHub Actions artifacts
|
||
|
|
|
||
|
|
**UI:**
|
||
|
|
- `lib/menu.js` - Main interactive menu
|
||
|
|
- `lib/banner.js` - Gradient color scheme (purple/pink/gold theme), headers
|
||
|
|
|
||
|
|
### GitHub API Integration
|
||
|
|
|
||
|
|
**Rate Limiting:**
|
||
|
|
- Unauthenticated: 60 requests/hour
|
||
|
|
- OAuth authenticated: 5,000 requests/hour
|
||
|
|
- Rate limit handler in `lib/github-api.js` prompts user to wait/skip/abort
|
||
|
|
- OAuth setup via device flow in `lib/github-oauth.js`
|
||
|
|
|
||
|
|
**Indexing Strategy:**
|
||
|
|
- Parses markdown with regex: `- [Name](url) - Description`
|
||
|
|
- Detects awesome lists vs regular repos by name/description patterns
|
||
|
|
- Recursive crawling with level tracking for hierarchy
|
||
|
|
- Stores raw and processed content for diff-based updates
|
||
|
|
|
||
|
|
### Search Architecture
|
||
|
|
|
||
|
|
**FTS5 Implementation:**
|
||
|
|
- Indexes: repository name, description, content, tags, categories
|
||
|
|
- Content preprocessing in `lib/indexer.js`: strips code blocks, HTML, normalizes whitespace
|
||
|
|
- Query through `db-operations.js:searchReadmes()` using MATCH operator
|
||
|
|
- Results ranked by BM25 relevance score
|
||
|
|
|
||
|
|
### Export Capabilities
|
||
|
|
- Markdown with awesome-style badges
|
||
|
|
- JSON structured data
|
||
|
|
- PDF/EPUB via `markdown-pdf` and `epub-gen` (dependencies installed)
|
||
|
|
|
||
|
|
## Development Patterns
|
||
|
|
|
||
|
|
### Error Handling
|
||
|
|
- GitHub API errors display user-friendly prompts with wait/skip/abort options
|
||
|
|
- Rate limit detection via response headers (`x-ratelimit-remaining`)
|
||
|
|
- Special error code `'SKIP_RATE_LIMIT'` to skip remaining items
|
||
|
|
|
||
|
|
### Database Operations
|
||
|
|
- Uses prepared statements exclusively
|
||
|
|
- Foreign keys enabled with cascade deletes
|
||
|
|
- Content versioning via SHA256 hashing
|
||
|
|
- WAL mode for concurrent access
|
||
|
|
|
||
|
|
### UI Patterns
|
||
|
|
- Consistent gradient theme via `banner.js` color functions
|
||
|
|
- Loading states using `ora` and `nanospinner`
|
||
|
|
- Progress bars via `cli-progress` for batch operations
|
||
|
|
- Tables with `cli-table3` for result display
|
||
|
|
|
||
|
|
### State Management
|
||
|
|
- Database is single source of truth
|
||
|
|
- Shell history persisted to `~/.awesome/shell_history.txt`
|
||
|
|
- Settings stored in database `settings` table as key-value pairs
|
||
|
|
- OAuth tokens encrypted and stored in settings
|
||
|
|
|
||
|
|
## Important Notes
|
||
|
|
|
||
|
|
- **First Run:** Two options:
|
||
|
|
- Fast: `./awesome db` to download pre-built database from GitHub Actions
|
||
|
|
- Slow: `./awesome index` to build the search index locally (1-2 hours)
|
||
|
|
- **Native Module:** better-sqlite3 requires rebuild after installation
|
||
|
|
- **OAuth Recommended:** Dramatically increases API rate limits (see `OAUTH_SETUP.md`)
|
||
|
|
- **Data Location:** All data in `~/.awesome/` directory
|
||
|
|
- **Hierarchical Structure:** awesome_lists table uses parent_id for tree relationships
|
||
|
|
- **Content Hashing:** README versions tracked by SHA256 to enable smart updates with diffs
|
||
|
|
- **GitHub Actions:** Automated workflows build database daily and clean up old artifacts
|
||
|
|
- **Artifact Download:** CLI command `./awesome db` provides interactive database download
|