gh-celebs/README.md

# gh-celebs

A fast, non-interactive CLI tool for searching GitHub repositories by popularity (stars). Uses a local SQLite database that learns and grows as you search.

## Features

- **Smart Caching**: Searches local database first, only hits GitHub API when needed
- **Popularity-Based**: Results sorted by star count (descending)
- **Dual Output Modes**: Clean plain text (default) or JSON (`--json`)
- **Repository Updates**: Refresh cached repo data with a single command
- **Rate Limit Awareness**: Displays remaining API calls and warns when running low
- **Configurable**: Optional GitHub token for higher rate limits (30 vs 10 calls/minute)
- **Cross-Platform**: Works on Linux, macOS, and Windows

## Installation

### From Source

```bash
git clone https://github.com/yourusername/gh-celebs
cd gh-celebs
cargo build --release
```

The binary will be available at `target/release/gh-celebs`.

### Prerequisites

- Rust 1.70+ (for building from source)
- GitHub account (optional, for higher API rate limits)

## Usage

### Search for Repositories

```bash
# Search for "react" (default: top 5 results)
gh-celebs react

# Search with custom limit
gh-celebs react --limit 10
gh-celebs react -n 10

# JSON output for scripting
gh-celebs react --json

# Combine options
gh-celebs machine learning --limit 20 --json
```

### Update Cached Repositories

```bash
# Update all cached repositories
gh-celebs update

# Update a specific repository
gh-celebs update facebook/react
```

### Help

```bash
gh-celebs --help
gh-celebs update --help
```

## Example Output

### Plain Text (Default)

```
1. facebook/react (220,473 ⭐) - Updated 2026-01-15
   https://github.com/facebook/react
   A declarative, efficient, and flexible JavaScript library for building user interfaces.

2. vuejs/vue (210,123 ⭐) - Updated 2026-01-14
   https://github.com/vuejs/vue
   Vue.js is a progressive, incrementally-adoptable JavaScript framework...

3. vercel/next.js (105,234 ⭐) - Updated 2026-01-16
   https://github.com/vercel/next.js
   The React Framework for the Web

API: [8/10 calls remaining]
```

### JSON Output

```json
{
  "query": "react",
  "limit": 5,
  "api_remaining": 8,
  "api_limit": 10,
  "total_cached": 1247,
  "results": [
    {
      "rank": 1,
      "full_name": "facebook/react",
      "stars": 220473,
      "html_url": "https://github.com/facebook/react",
      "description": "A declarative, efficient, and flexible JavaScript library...",
      "language": "JavaScript",
      "cached_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

## Configuration

### Config File Location

- **Linux**: `~/.config/gh-celebs/config.toml`
- **macOS**: `~/Library/Application Support/com.gh-celebs.gh-celebs/config.toml`
- **Windows**: `%APPDATA%\gh-celebs\gh-celebs\config\config.toml`

### GitHub Token (Optional)

Add a GitHub personal access token to increase rate limits from 10 to 30 requests per minute:

```toml
[github]
token = "ghp_xxxxxxxxxxxxxxxxxxxx"
```

To create a token:
1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Generate a new token (no scopes required for public repo search)
3. Add it to your config file

### Database Location

The local SQLite database is stored alongside the config:

- **Linux**: `~/.local/share/gh-celebs/repos.db`
- **macOS**: `~/Library/Application Support/com.gh-celebs.gh-celebs/repos.db`
- **Windows**: `%APPDATA%\gh-celebs\gh-celebs\data\repos.db`

## How It Works

1. **Local Search**: When you run a query, the tool first searches the local SQLite database for cached repositories matching your query (by name or description).

2. **API Fallback**: If local results are insufficient, the tool queries the GitHub Search API for additional repositories.

3. **Smart Caching**: API results are automatically cached to the local database for future searches.

4. **Merging & Sorting**: Local and API results are merged, sorted by star count, and the top N results are returned.

5. **Updates**: Use the `update` command to refresh star counts and metadata for cached repositories.

## Rate Limits

- **Anonymous**: 10 requests per minute
- **Authenticated**: 30 requests per minute (with token)

The tool displays remaining API calls and warns when running low:

```
Warning: Rate limit running low (2 remaining)
```

## Tech Stack

- **Language**: Rust
- **Database**: SQLite (via `rusqlite`)
- **HTTP Client**: `reqwest` (async)
- **CLI**: `clap` (derive-based)
- **Serialization**: `serde`
- **Error Handling**: `anyhow`

## Project Structure

```
gh-celebs/
├── Cargo.toml
├── README.md
└── src/
    ├── main.rs       # Entry point and orchestration
    ├── cli.rs        # CLI argument definitions
    ├── config.rs     # Configuration loading
    ├── db.rs         # Database operations
    ├── github.rs     # GitHub API client
    ├── models.rs     # Data structures
    ├── output.rs     # Output formatters
    └── search.rs     # Search logic
```

## OpenCode Integration

This project includes an **OpenCode skill** located at `.opencode/skills/gh-celebs/SKILL.md` that enables AI assistants to search GitHub repositories using gh-celebs.

The skill provides:
- Automated command construction based on natural language queries
- Rate limit awareness and error handling
- Best practices for searching and updating repositories
- Integration with the OpenCode skill system

For AI assistants: When users ask to "search GitHub repositories", "find popular GitHub repos", or similar queries, use the gh-celebs skill to execute the search.

## Exit Codes

- `0` - Success
- `1` - Error (invalid arguments, API errors, etc.)

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Future Enhancements

- [ ] Filter by language (`--lang rust`)
- [ ] Sort options (`--sort updated`, `--sort created`)
- [ ] Export to CSV/JSON file (`--export results.json`)
- [ ] Fuzzy search matching
- [ ] Configurable database location

## Acknowledgments

Built with ❤️ using Rust and the GitHub API.