Metadata-Version: 2.4
Name: gh-social
Version: 1.1.9
Summary: CLI tools for GitHub — follow back, unfollow, and more.
Author: Ajang Supardi
License-Expression: MIT
Project-URL: Homepage, https://github.com/ajangsupardi/gh-social
Project-URL: Repository, https://github.com/ajangsupardi/gh-social
Keywords: github,cli,follow,unfollow,toolkit
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: pyright>=1.1.350; extra == "dev"
Dynamic: license-file

# gh-social

CLI tools for GitHub — follow back, unfollow, and more.

A fast, modular toolkit for common GitHub operations. Includes **Follow Back**, **Unfollow**, and **Follow Stargazers** tools.

## Tools

| Tool | Description |
|------|-------------|
| `follow` | Follow all followers of any GitHub user |
| `unfollow` | Unfollow users who don't follow you back |
| `stargazers` | Follow users who starred a repository |

### Features

- **Interactive Menu** — Run without arguments for a guided menu experience
- **Concurrent Execution** — Uses `ThreadPoolExecutor` with 16 workers for fast API operations
- **Smart Bot Detection** — Identifies spam/bot accounts using a 2-of-3 heuristic
- **Dry-Run Mode** — Preview targets before executing any actions
- **Rate Limit Aware** — Checks GitHub API rate limits before proceeding
- **JSON Output** — Machine-readable output for scripting and automation

## Requirements

- Python 3.10+
- [GitHub CLI](https://cli.github.com/) (`gh`) — must be installed and authenticated
- `rich` >= 13.0 — modern terminal output

### Authentication

The toolkit uses your `gh` CLI credentials:

```bash
gh auth login
gh auth refresh -h github.com -s user
```

## Installation

> **Note:** On Debian/Ubuntu 23.04+ the system Python is externally managed (PEP 668).
> Use a virtual environment or `pipx` to avoid installation errors.

### With pipx (Recommended)

```bash
pipx install gh-social
```

### From PyPI

```bash
pip install gh-social
```

### From Source (Development)

```bash
git clone https://github.com/ajangsupardi/gh-social.git
cd gh-social
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Usage

### Interactive Mode

Run without arguments to see the menu:

```bash
gh-social
```

### CLI Mode

```bash
# Follow Back
gh-social follow ajangsupardi              # Dry-run
gh-social follow ajangsupardi --execute    # Execute
gh-social follow ajangsupardi --limit 100  # Limit

# Follow Stargazers
gh-social stargazers ajangsupardi/gh-social              # Dry-run
gh-social stargazers ajangsupardi/gh-social --execute    # Execute
gh-social stargazers ajangsupardi/gh-social --limit 50   # Limit

# Unfollow
gh-social unfollow                         # Dry-run
gh-social unfollow --execute               # Execute
gh-social unfollow --limit 100             # Limit

# Common flags
gh-social follow ajangsupardi --json       # JSON output
gh-social follow ajangsupardi --execute --include-bots
```

### As Library

```python
from gh_social.api import get_session, api_paginate, follow_user
from gh_social.models import enrich_users_concurrent

# Initialize session
get_session()

# Use API functions directly
followers = api_paginate("users/octocat/followers")
follow_user("octocat")
```

## Flags

| Flag | Description | Default |
|------|-------------|---------|
| `--execute` | Execute action (otherwise dry-run) | `false` |
| `--limit N` | Limit number of users processed | `0` (all) |
| `--include-bots` | Include bot accounts | `false` |
| `--json` | Output in JSON format | `false` |

## How It Works

### Follow Back

```
1. Authenticate via gh CLI token
2. Fetch target user's followers (paginated, concurrent)
3. Fetch your following list to identify already-followed users
4. Filter out: yourself, already-followed, and optionally bots
5. Enrich user details concurrently (name, bio, repos)
6. Display table preview (dry-run) or execute follows concurrently
```

### Unfollow

```
1. Authenticate via gh CLI token
2. Fetch your followers & following lists (concurrent)
3. Find: users you follow who DON'T follow you back
4. Filter out: optionally bots
5. Enrich user details concurrently (name, bio, repos)
6. Display table preview (dry-run) or execute unfollows concurrently
```

### Follow Stargazers

```
1. Authenticate via gh CLI token
2. Fetch stargazers of target repo (paginated, concurrent)
3. Fetch your following list to identify already-followed users
4. Filter out: yourself, already-followed, and optionally bots
5. Enrich user details concurrently (name, bio, repos)
6. Display table preview (dry-run) or execute follows concurrently
```

## Bot Detection

Accounts are flagged as potential bots when **2 out of 3** conditions are met:

| Condition | Description |
|-----------|-------------|
| Default avatar | Uses GitHub's default identicon |
| Empty bio | No bio or whitespace only |
| Zero repos | No public repositories |

## License

MIT License — see [LICENSE](LICENSE) for details.
