Metadata-Version: 2.1
Name: commitpulse
Version: 0.1.3
Summary: Premium Git repository analytics and dashboard generator
Author: Samuel Olubukun
Project-URL: Homepage, https://github.com/samolubukun/commitpulse
Project-URL: Repository, https://github.com/samolubukun/commitpulse
Project-URL: Issues, https://github.com/samolubukun/commitpulse/issues
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

# Commit Pulse 💎
A premium, high-fidelity Git repository analytics engine and dashboard generator. Built for engineers who care about their legacy.

- **Author**: Samuel Olubukun
- **Repository**: [github.com/samolubukun/commitpulse](https://github.com/samolubukun/commitpulse)
- **License**: MIT

Commit Pulse is a powerful, locally-first CLI tool that generates high-fidelity engineering dashboards for your Git repositories. It analyzes your development ecosystem, visualizes commit intensity heatmaps, and identifies top contributors using real GitHub profiles.

## ✨ Key Features
- **Zero-PAT Analysis**: Analyzes local `.git` metadata directly. No Personal Access Tokens or cloud APIs required for core stats.
- **Accurate Project Timelines**: Dynamic contribution grids that span from the repository's inception to the **last official commit**.
- **GitHub Profile Integration**: Automatically fetches actual contributor avatars via the public GitHub Search API.
- **Master Scan**: A recursive drive scanner that aggregates stats from every project on your machine into a single interactive dashboard.
- **Premium Aesthetics**: Glassmorphic UI with dark mode, smooth animations, and official GitHub iconography.

## 📦 Installation

### 1. Local (Developer Mode)
If you have the source code locally:
```bash
pip install -e .
```

### 2. Direct from GitHub
Anyone can install your tool directly if the repo is public:
```bash
pip install git+https://github.com/YOUR_USERNAME/commitpulse.git
```

### 3. Global Command
Once installed, the `commitpulse` command is available everywhere in your terminal.

## 🚀 Usage

### Publish current repository to Cloud (Default)
```bash
commitpulse
```

### Analyze all repositories on your computer (Master Scan & Publish)
```bash
commitpulse --scan
```

### Generate a Local HTML Dashboard
```bash
commitpulse --local
```

### Specify a target directory
```bash
commitpulse /path/to/projects
```

## 🛠️ Options
- `--scan`: Crawls subdirectories to find and aggregate all Git repositories.
- `--local`: Generates a self-contained, interactive HTML dashboard on your machine.
- `--no-open`: Prevents the CLI from automatically opening the results in the browser.

## 🚀 Deployment & Sharing

Commit Pulse offers two ways to view and share your results:

### 1. Commit Pulse Cloud (Default Workflow)
Ready to show the world? Simply run the base command to host your dashboard on the global registry and get a unique, shareable URL.
```bash
commitpulse
```
*Output: `https://commitpulse.pxxl.click/v/your-unique-id`*

### 2. Local-First (Private Analysis)
Use the `--local` flag to generate a static HTML dashboard strictly on your machine.
```bash
commitpulse --local
```
*Output: `stats_dashboard.html` (Requires 'y' confirmation)*

---

## 🛠️ Setting up your own Cloud Instance (Optional)

If you are hosting your own version of **Commit Pulse Cloud**:

1.  **Neon DB**:
    - Go to [Neon.tech](https://neon.tech) and create a free project.
    - Copy your **Connection String** (e.g., `postgresql://user:pass@ep-cool-beach-123.us-east-2.aws.neon.tech/neondb?sslmode=require`).
2.  **Environment Setup**:
    - In the `commitpulse-cloud` directory, rename `.env.example` to `.env`.
    - Paste your connection string into `DATABASE_URL`.
3.  **Vercel Deployment**:
    - Deploy the `commitpulse-cloud` folder to Vercel.
    - Add the `DATABASE_URL` to your Vercel Environment Variables.

## 🌍 Distribution & PyPI Hosting

To share **Commit Pulse** with the global developer community via PyPI:

### 1. Prepare your Account
- Register at [pypi.org](https://pypi.org/).
- Generate an API Token in your account settings.

### 2. Build the Distribution
Ensure you have the latest build tools:
```bash
python -m pip install --upgrade build twine
```
Then build the package:
```bash
python -m build
```
This creates a `dist/` folder with your `.whl` and `.tar.gz` files.

### 3. Upload to PyPI
Use `twine` to securely upload your package:
```bash
python -m twine upload dist/*
```
- **Username**: `__token__`
- **Password**: `[Your API Token]`

Once uploaded, anyone can install it via:
```bash
pip install commitpulse
```

---
*Built with ❤️ for the development ecosystem.*
