Metadata-Version: 2.4
Name: autocommitbot
Version: 1.4.3
Summary: Automatic GitHub commit bot that logs developer activity.
Author: Rohit
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: requests
Requires-Dist: gitpython
Requires-Dist: questionary
Requires-Dist: pyfiglet
Dynamic: license-file

# 🚀 AutoCommitBot (v1.4.0)

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](#license)
[![GitHub activity](https://img.shields.io/badge/github-automated-orange.svg)](https://github.com/RohitKSahoo/auto-commit-bot)

**Maintain a professional GitHub presence with AI-powered automation and built-in security.**

AutoCommitBot is an intelligent CLI tool for developers who want a consistent contribution history without the manual overhead. It monitors your local repositories, generates meaningful commit messages using Google's Gemini AI, and manages the full Git lifecycle automatically — all authenticated through the GitHub CLI so no tokens or passwords ever need to be configured by hand.

---

## 🖥️ Preview

<p align="center">
  <img src="assets/CLI.png" alt="AutoCommitBot CLI" width="750"/>
</p>

---

## 🌟 Why AutoCommitBot?

* **Zero-friction auth** — Piggybacks on your existing `gh` login; no tokens, no PATs, no manual username entry
* **AI Commit Messages** — Generates meaningful, context-aware commits instead of generic updates
* **Security (Secret Shield)** — Prevents accidental exposure of sensitive files and credentials
* **Natural Activity Mode** — Simulates realistic developer commit patterns
* **Manual vs. Background Control** — **[NEW]** Choose between interactive manual runs and strictly automated background heartbeats
* **Backup & Restore** — Enables complete rollback of local and remote states
* **Automated Execution** — Runs seamlessly in the background on system logon

---

## ✨ Features

### Core Capabilities

* **GitHub CLI Auth** — Identity verified through your active `gh` session; repos fetched & cloned via `gh` automatically
* **AI Commit Generation** — Context-aware commit messages using Gemini with model fallback
* **Security Layer (Secret Shield)** — Automatic protection against sensitive file and credential exposure
* **Interactive Manual Mode** — **[NEW]** Choose whether to commit real work or perform a Heartbeat commit manually
* **Strict Background Heartbeats** — **[NEW]** Background tasks now strictly perform "Random Activity" commits to maintain streaks without cluttering code history
* **Scheduling Engine** — Supports logon, fixed-time, and natural activity-based execution
* **Backup & Restore** — Pre-commit snapshots with full local and remote rollback capability
* **Dashboard & Analytics** — CLI-based insights into commit history and activity
* **Execution Reliability** — Built-in retry logic, conflict handling, and network checks
* **Decent CLI Theme** — Clean, professional, and subtle color-coded output for repository tracking
* **Secret Shield** — Now includes refined visual markers for protected and exposed files


<details>
<summary>🔍 View Full Feature Breakdown</summary>

### ⚙️ Setup & Configuration

* Identity verified via GitHub CLI (`gh auth login`) — no username prompt, no tokens
* Repository list fetched with `gh repo list` (authenticated)
* Interactive multi-select repo setup
* Base folder configuration
* Automatic cloning via `gh repo clone` (inherits your `gh` session)
* Git authentication verification
* Backward navigation during setup

---

### 🕐 Scheduling System

* Logon trigger (Windows Task Scheduler) — **Strictly performs Random Activity (Heartbeat) commits in the background**
* Fixed-time daily scheduling
* Randomized daily execution (9 AM – 11 PM)
* Natural Activity Mode (probabilistic commits with 48h enforcement)
* Runs with highest privileges
* Works on battery power

---

### 🔁 Commit Engine

* Smart change detection across repositories
* **Manual Run:** Interactive menu to choose between User Changes vs. Heartbeat
* **Background Run:** Strictly Heartbeat (Random Activity) mode
* Automatic pull → merge → push workflow
* Push retry logic on failure

---

### 🤖 AI Commit System

* Gemini AI integration for commit messages
* **AI Key Validation** — Real-time verification of your API key during setup
* Model fallback chain: 2.5 Flash → 2.0 Flash → 1.5 Flash → Pro
* Diff truncation for large inputs (8000 chars)

---

### 💾 Backup & Restore

* ZIP snapshot before every commit
* Configurable backup retention (`config-backup`)
* Restore command with snapshot selection
* Automatic GitHub rollback via force push
* Clear all backups on demand (`clear-backups`)

---

### 📊 Dashboard & Management

* Dashboard with last 50 commits (rich table view)
* Commit classification (User vs Activity)
* Status command for tracked repos
* Add/remove repositories dynamically
* Persistent history tracking (500 entries)
* Clean uninstall command — removes scheduler task before uninstalling
* Version check command — shows installed version and detects available updates

---

### 🌐 Reliability Layer

* Internet availability check (retry up to 2 minutes)
* Automatic admin privilege escalation
* Resilient Git operations with fallback handling

</details>

---

## ⚙️ How It Works

1. Verifies your GitHub identity via the GitHub CLI (`gh`)
2. Detects changes in tracked repositories
3. Syncs with remote using `git pull`
4. Analyzes `git diff` using Gemini AI (in Manual mode)
5. Generates a contextual commit message
6. Runs security checks (Secret Shield)
7. Commits and pushes changes
8. Stores a backup snapshot

All of this runs automatically in the background.

---

## 🚀 Getting Started

### Prerequisites

Before installing AutoCommitBot, make sure you have all of the following:

| Requirement | Why it's needed | Get it |
|---|---|---|
| **Python 3.8+** | Runtime | [python.org](https://www.python.org/downloads/) |
| **Git** | Version control | [git-scm.com](https://git-scm.com/) |
| **GitHub CLI (`gh`)** | Identity verification & repo access | [cli.github.com](https://cli.github.com/) |
| **Gemini API key** *(optional but recommended)* | AI-generated commit messages | [aistudio.google.com](https://aistudio.google.com/app/apikey) |

> **Important:** AutoCommitBot v1.2.7+ requires the GitHub CLI. It uses your existing `gh` login to verify who you are and to fetch and clone your repositories — no passwords or personal-access tokens needed.

---

### Step 0 — Install & authenticate the GitHub CLI

If you haven't already:

```bash
# macOS (Homebrew)
brew install gh

# Windows (winget)
winget install --id GitHub.cli

# Debian / Ubuntu
sudo apt install gh
```

Then sign in:

```bash
gh auth login
```

Follow the interactive prompts (choose HTTPS, then authenticate via browser). Confirm it worked:

```bash
gh auth status
# → ✓ Logged in to github.com as YourUsername
```

---

## 📦 Installation

### Option 1: Via pip (Recommended)

```bash
pip install autocommitbot
```

### Option 2: From Source

```bash
git clone https://github.com/RohitKSahoo/auto-commit-bot.git
cd auto-commit-bot
pip install -e .
```

---

## 🛠️ First-Time Setup

Run the setup wizard once after installation:

```bash
autocommit setup
```

The wizard will:

1. **Verify your GitHub identity** via `gh auth status` — no username prompt
2. **Fetch your repositories** from GitHub using `gh repo list`
3. Let you **select which repos** to automate (multi-select checklist)
4. Ask for a **base folder** where repos should be cloned if not already present
5. Ask you to pick a **schedule** (on logon / fixed time / natural activity)
6. Optionally let you enter a **Gemini API key** for AI commit messages

> **Tip:** Running `autocommit setup` again on an already-configured machine shows a short menu so you can update just one section (Repositories, Schedule, or AI key) without repeating the full wizard. On a fresh install the full wizard always runs — no menu.

---

## 🛠️ Usage

All commands follow the pattern: `autocommit <command>`

> Run `autocommit <command> --help` for full details on any command.

### ⚙️ Setup & Config

| Command | What it does |
|---|---|
| `autocommit setup` | First-time wizard, **or** edit repos / schedule / AI |
| `autocommit config-backup <days>` | Set how long backups are kept |

### 📁 Repositories

| Command | What it does |
|---|---|
| `autocommit add [path]` | Track a new local git repo |
| `autocommit remove` | Stop tracking a repo |
| `autocommit status` | List all tracked repos |

### 🔁 Automation

| Command | What it does |
|---|---|
| `autocommit run` | **[Interactive]** Commit changes or heartbeat now |
| `autocommit enable` | Register the Windows auto-start task |
| `autocommit disable` | Remove the Windows auto-start task |

### 📊 History & System

| Command | What it does |
|---|---|
| `autocommit dashboard` | View commit history & stats |
| `autocommit restore` | Roll back a bot commit from snapshot |
| `autocommit clear-backups` | Delete all backup snapshots to free disk space |
| `autocommit version` | Check installed version & updates |
| `autocommit uninstall` | Remove scheduler task then pip uninstall |

---

### ⚠️ Notes

* **GitHub CLI required** — `autocommit setup` will exit with a clear error if `gh` is not installed or you're not logged in
* Automation runs only on tracked repositories
* `restore` performs a **force push** — rewrites remote history, use with caution
* `run` is for manual triggering, not regular use
* Internet connection required for push, version check, and AI commit messages
* **On Logon mode** caps **random activity** at 5 per calendar day — real code changes always push through, even after the cap is reached
* Always use `autocommit uninstall` instead of `pip uninstall` directly — running pip uninstall alone will leave an orphaned task in Windows Task Scheduler that silently fails on every trigger

---

## 🔄 Staying Up to Date

Run the following command to check your current version and see if a newer release is available:

```bash
autocommit version
```

Example output when up to date:
```
AutoCommitBot  v1.3.0
Checking for updates...
✔ You are on the latest version (1.3.0).

🎉 New in this version (v1.3.0):
  • Fixed background hangs in Task Scheduler by redirecting output to logs
  • Added global timeouts to all Git operations to prevent indefinite stalls
  • Fixed encoding crashes on Windows (UTF-8 support for log files)
  • Optimized Secret Shield performance for faster repository scanning
  • Shortened scheduler commands to fit within Windows path limits
```

Example output when an update is available:
```
AutoCommitBot  v1.2.7
Checking for updates...
⚡ New version available: 1.2.8 (you have 1.2.7)

📋 What's New in v1.2.9:
  • Refined, easier-on-the-eyes color theme for better commit and security tracking
  • Setup wizard now pre-selects existing repos and suggests your base folder
  • Fixed a bug in the setup flow that prevented repository updates from saving

Run to update:  pip install --upgrade autocommitbot
```

To update manually at any time:

```bash
pip install --upgrade autocommitbot
```

---

## 🔐 Security Notes

* Your code is **not stored externally** (only analyzed for commit messages)
* Sensitive files are automatically excluded via `.gitignore`
* Identity is verified through your local `gh` session — no credentials are stored by AutoCommitBot
* `restore` uses **force push** — use with caution

---

## 🆘 Support & Contributions

* Report issues: https://github.com/RohitKSahoo/auto-commit-bot/issues
* Contributions welcome (see `CONTRIBUTING.md`)
* Additional docs in `/docs`

---

## 👤 Maintainer

Maintained by **[@RohitKSahoo](https://github.com/RohitKSahoo)**

---

## 📄 License

This project is licensed under the GNU General Public License v3.0.

You are free to use, modify, and distribute this software under the terms of the license. Any derivative work must also be open-sourced under GPL v3.

See the LICENSE file for full details.

---

## 🧾 TL;DR

AutoCommitBot is a smart Git automation layer with AI, security, and recovery built in — authenticated entirely through your existing GitHub CLI session.
