Metadata-Version: 2.4
Name: clonepulse
Version: 0.9.0
Summary: Your GitHub clone stats, visualized and celebrated.
Project-URL: Homepage, https://github.com/per2jensen/clonepulse
Project-URL: Issues, https://github.com/per2jensen/clonepulse/issues
Author-email: Per Jensen <clonepulse@pm.me>
License: MIT License
        
        Copyright (c) 2025 Per Jensen
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.9
Requires-Dist: matplotlib>=3.10.3
Requires-Dist: pandas>=2.3.0
Requires-Dist: requests>=2.32.2
Provides-Extra: dev
Requires-Dist: coverage>=7.8.2; extra == 'dev'
Requires-Dist: matplotlib>=3.10.3; extra == 'dev'
Requires-Dist: pandas>=2.3.0; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
Requires-Dist: pytest>=8.4.0; extra == 'dev'
Requires-Dist: requests>=2.32.2; extra == 'dev'
Requires-Dist: wheel>=0.45.1; extra == 'dev'
Provides-Extra: packaging
Requires-Dist: build>=1.2.2; extra == 'packaging'
Requires-Dist: hatch>=1.14.1; extra == 'packaging'
Requires-Dist: hatchling>=1.27.0; extra == 'packaging'
Requires-Dist: twine>=6.1.0; extra == 'packaging'
Description-Content-Type: text/markdown

# 📈 ClonePulse

**Your GitHub clone stats, visualized and celebrated.**  
Track weekly trends, highlight milestones, and share visual dashboards—all automatically.

[![Use this template](https://img.shields.io/badge/-Use%20this%20template-2ea44f?style=for-the-badge&logo=github)](https://github.com/per2jensen/clonepulse/generate)

---

## 🚀 What is ClonePulse?

`ClonePulse` is a GitHub-friendly toolchain that fetches, tracks, and visualizes repository clone activity.

It offers:

- ✅ **Daily clone tracking** (total + unique)
- 📊 **12-week visual dashboard** (.PNG image)
- 📌 **Automatic milestone detection** (e.g., 500, 1K, 2K+ clones)
- 🏷️ **Auto-annotations** for clone spikes
- 🏁 **Badge generation** for README inclusion
- 🤖 **GitHub Actions** support for automation

---

## Example badge setup

[![# clones](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/per2jensen/clonepulse/main/badges/badge_clones.json)](https://github.com/per2jensen/clonepulse/blob/main/doc/weekly_clones.png)
[![Milestone](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/per2jensen/clonepulse/main/badges/milestone_badge.json)](https://github.com/per2jensen/clonepulse/blob/main/doc/weekly_clones.png)

---

## 🏷️ ClonePulse Badge Snippet

```text
[![# clones](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/<your-username>/<your-repo>/main/badges/badge_clones.json)](https://github.com/<your-username>/<your-repo>/blob/main/doc/weekly_clones.png)

[![Milestone](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/<your-username>/<your-repo>/main/badges/milestone_badge.json)](https://github.com/<your-username>/<your-repo>/blob/main/doc/weekly_clones.png)
```

✅ Instructions:

Replace \<your-username\> and \<your-repo\> with your actual GitHub handle and repository name.

Ensure the `fetch_clones.yml` and `generate_clone_dashboard.yml` GitHub Actions are set up, enabled and working. Run them manually to check.

The badges will auto-update based on your repo's clone activity, and clicking the badges will show the latest dashboard.

---

## 📷 Example Dashboard

> A weekly clone activity chart is automatically updated and saved in `doc/weekly_clones.png`.

It is intended to run every Monday morning. Data from the current week is discarded - only data for full weeks are shown.

![Clone Dashboard Example](doc/weekly_clones.png)

---

## 🔐 Creating a Secure GitHub Token for ClonePulse

ClonePulse fetches traffic (clone) stats from the GitHub API. This requires a Personal Access Token (PAT) with read-only access to repository traffic. Here's how to create one securely and use it with GitHub Actions.

### Token Requirements

For public repositories, a fine-grained token with Repository traffic (read-only) access is sufficient.

For private repositories, you will also need:

- Repository contents: Read-only
- Repository metadata: Read-only
- Repository traffic: Read-only

### 🛠️ How to Create a Fine-Grained Token

Visit: https://github.com/settings/tokens

Click "Generate new token" → "Fine-grained token"

Configure:

Name: e.g., ClonePulse fetch token

Expiration: e.g., 90 days

Resource owner: Your user or organization

Repository access: Select the **specific repo**

Permissions:

- "Read access to administration and metadata ": Read-only
- (Add others like contents if your repo is private)

Click "Generate token" and copy it immediately

### 🔒 Overview of securing the Token Using GitHub Secrets

1. Go to your GitHub repository:  
   **Settings → Secrets and variables → Actions → New repository secret**

2. Name the secret:  
   `CLONEPULSE_METRICS`

3. Paste the token you copied and save.

### 🚀 GitHub Action workflow `fetch_clones.yml`

The workflow references the secret as an environment variable:

```yaml
- name: Run fetch_clones.py
  env:
    TOKEN: ${{ secrets.CLONEPULSE_METRICS }}
  run: python src/clonepulse/fetch_clones.py
```

The workflows must be enabled and perhaps the crontab needs adjusting to your taste.

## 🛠️ Installation (dev setup)

```bash
git clone https://github.com/your-user/clonepulse.git
cd clonepulse
./build.sh  # Creates virtualenv and installs dependencies
```

## 🤝 Contributing

Found a bug or have a suggestion?  
Feel free to [open an issue](https://github.com/your-user/clonepulse/issues) or submit a pull request!
