gitfollow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b4f29850531cd95147f1f6c98b63ac4e2308568d3a3e949ecb6f30d6e9f22444
+  data.tar.gz: 14a0e59f5e86a739786521b4cd42c1a8fc0e90809624a8d4dd6d9d7ada0ba478
+SHA512:
+  metadata.gz: 0c213737148a7fb1859878f0647199ddfa78e9cd16fac70540632b343bba6130574c33cff5735a4426d396408e8c013e4f1acccd02e8ac0a5e2f43ef0eeaf16f
+  data.tar.gz: 517e34220cc9afe3a90fd89691b8779ec686ca3bdc331ec527232cc98a3dcd9b05f5f69755a1163fa0d0e7d28273b1f42af64ca60a48e23b30b47824caddb432

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-10-07
+
+### Added
+- Initial release of GitFollow
+- Track GitHub followers and unfollows
+- Detect new followers automatically
+- Detect unfollows automatically
+- Store follower history with timestamps
+- Generate detailed reports (text and markdown)
+- Display follower statistics
+- List mutual followers
+- List non-followers (users you follow who don't follow back)
+- Export data to JSON format
+- Export data to CSV format
+- Create GitHub Issues automatically on changes
+- Colorized terminal output
+- Formatted table output with TTY::Table
+- Progress spinners for API calls
+- JSON output mode for all commands
+- CLI commands:
+  - `gitfollow init` - Initialize and create first snapshot
+  - `gitfollow check` - Check for follower changes
+  - `gitfollow report` - Generate detailed report
+  - `gitfollow stats` - Display statistics
+  - `gitfollow mutual` - List mutual followers
+  - `gitfollow non-followers` - List non-followers
+  - `gitfollow export` - Export data
+  - `gitfollow clear` - Clear all stored data
+  - `gitfollow version` - Display version
+- GitHub Actions workflows:
+  - CI workflow with tests and linting
+  - Daily follower check workflow
+  - Automated release workflow
+- Comprehensive test suite with RSpec
+- RuboCop configuration for code quality
+- Support for Ruby 3.0, 3.1, 3.2, and 3.3
+- MIT License
+- Complete documentation
+
+### Security
+- GitHub token authentication
+- Rate limit aware API calls
+- No credentials stored in data files
+
+[Unreleased]: https://github.com/bulletdev/gitfollow/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/bulletdev/gitfollow/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael D. Bullet
+
+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.

data/README.md

@@ -0,0 +1,437 @@
+# GitFollow
+
+[![CI](https://github.com/bulletdev/gitfollow/workflows/CI/badge.svg)](https://github.com/bulletdev/gitfollow/actions)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0-ruby.svg)](https://www.ruby-lang.org)
+[![Gem Version](https://badge.fury.io/rb/gitfollow.svg)](https://badge.fury.io/rb/gitfollow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/bulletdev/gitfollow/branch/main/graph/badge.svg)](https://codecov.io/gh/bulletdev/gitfollow)
+
+**GitFollow** is a powerful CLI tool to track your GitHub followers and unfollows with ease. Get notified when someone follows or unfollows you, generate detailed reports, and automate your follower monitoring with GitHub Actions.
+
+## Features
+
+**Core Features**
+- 🔍 Track new followers in real-time
+-  Detect unfollows automatically
+-  Generate detailed statistics and reports
+-  Maintain complete history with timestamps
+-  Create GitHub Issues automatically on changes
+-  Local JSON-based storage
+
+**Beautiful Output**
+- Colorized terminal output
+- Formatted tables (TTY::Table)
+- Progress spinners
+- Markdown and plain text reports
+
+**Developer-Friendly**
+- JSON export support
+- CSV export for data analysis
+- Configurable data directory
+- Rate limit aware
+- Comprehensive error handling
+
+## Installation
+
+### Via RubyGems (Recommended)
+
+```bash
+gem install gitfollow
+```
+
+### From Source
+
+```bash
+git clone https://github.com/bulletdev/gitfollow.git
+cd gitfollow
+bundle install
+gem build gitfollow.gemspec
+gem install ./gitfollow-0.1.0.gem
+```
+
+## Configuration
+
+### GitHub Token
+
+GitFollow requires a GitHub Personal Access Token with appropriate permissions.
+
+1. **Generate a token**: Go to [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)
+2. **Required scopes**: `read:user` (to read your follower data)
+3. **Set the token**:
+
+```bash
+export OCTOCAT_TOKEN="your_github_token_here"
+```
+
+Or create a `.env` file:
+
+```bash
+OCTOCAT_TOKEN=your_github_token_here
+```
+
+## Usage
+
+### Initialize GitFollow
+
+First, initialize GitFollow to create your first snapshot:
+
+```bash
+gitfollow init
+```
+
+**Output:**
+```
+✔ Fetching initial data... Done!
+
+Initialization complete!
+Username: @yourname
+Followers: 542
+Following: 123
+Mutual: 89
+
+Run 'gitfollow check' to detect changes.
+```
+
+### Check for Changes
+
+Check for new followers or unfollows:
+
+```bash
+gitfollow check
+```
+
+**Output:**
+```
+✔ Checking for changes... Done!
+
+Changes detected for @yourname
+
+✅ New Followers (2):
+  • @newuser1
+  • @newuser2
+
+❌ Unfollowed (1):
+  • @olduser
+
+Net change: +1
+Previous: 542 → Current: 543
+```
+
+### Display Statistics
+
+View your current follower statistics:
+
+```bash
+gitfollow stats
+```
+
+**Output:**
+```
+Follower Statistics for @yourname
+==================================================
+┌──────────────────────┬─────┐
+│Followers             │543  │
+│Following             │123  │
+│Mutual                │89   │
+│Ratio                 │4.41 │
+│Total New Followers   │15   │
+│Total Unfollows       │3    │
+└──────────────────────┴─────┘
+
+Last Updated: 2025-10-07 09:00:00 UTC
+```
+
+### Generate Reports
+
+Generate a detailed report:
+
+```bash
+# Plain text report
+gitfollow report
+
+# Markdown report
+gitfollow report --format=markdown
+
+# Save to file
+gitfollow report --format=markdown --output=report.md
+```
+
+### Find Mutual Followers
+
+List users who follow you and whom you follow back:
+
+```bash
+gitfollow mutual
+```
+
+### Find Non-Followers
+
+List users you follow who don't follow you back:
+
+```bash
+gitfollow non-followers
+```
+
+### Export Data
+
+Export your data for analysis:
+
+```bash
+# Export to JSON
+gitfollow export json data.json
+
+# Export to CSV
+gitfollow export csv data.csv
+```
+
+## Advanced Usage
+
+### JSON Output
+
+All commands support JSON output:
+
+```bash
+gitfollow check --json
+gitfollow stats --json
+gitfollow mutual --json
+```
+
+### Table Format
+
+Display changes in a formatted table:
+
+```bash
+gitfollow check --table
+```
+
+### Quiet Mode
+
+Suppress output if no changes detected:
+
+```bash
+gitfollow check --quiet
+```
+
+### Custom Data Directory
+
+Store data in a custom location:
+
+```bash
+gitfollow check --data-dir=/path/to/data
+```
+
+### Create GitHub Issues on Changes
+
+Automatically create an issue when changes are detected:
+
+```bash
+gitfollow check --notify="bulletdev/gitfollow"
+```
+
+## Automated Monitoring with GitHub Actions
+
+Set up automated daily checks using GitHub Actions:
+
+### 1. Create Workflow File
+
+Create `.github/workflows/daily-check.yml`:
+
+```yaml
+name: Daily Follower Check
+
+on:
+  schedule:
+    - cron: '0 9 * * *'  # Run daily at 9 AM UTC
+  workflow_dispatch:
+
+jobs:
+  check-followers:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+
+      - name: Install GitFollow
+        run: gem install gitfollow
+
+      - name: Cache data
+        uses: actions/cache@v4
+        with:
+          path: ~/.gitfollow
+          key: gitfollow-data
+
+      - name: Check followers
+        env:
+          OCTOCAT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gitfollow init || true
+          gitfollow check --notify="${{ github.repository }}"
+```
+
+### 2. Enable Workflow
+
+1. Push the workflow file to your repository
+2. Go to **Actions** tab in your repository
+3. Enable the workflow
+4. It will run automatically every day!
+
+## CLI Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `gitfollow init` | Initialize and create first snapshot |
+| `gitfollow check` | Check for follower changes |
+| `gitfollow report` | Generate detailed report |
+| `gitfollow stats` | Display statistics |
+| `gitfollow mutual` | List mutual followers |
+| `gitfollow non-followers` | List non-followers |
+| `gitfollow export FORMAT FILE` | Export data (json/csv) |
+| `gitfollow clear` | Clear all stored data |
+| `gitfollow version` | Display version |
+
+## Configuration File
+
+You can create a `.gitfollow.yml` config file (optional):
+
+```yaml
+# Custom data directory
+data_dir: ~/.gitfollow
+
+# Default notification repository
+notify_repo: bulletdev/gitfollow
+
+# Output preferences
+output:
+  colorize: true
+  format: table
+```
+
+## Data Storage
+
+GitFollow stores data in `~/.gitfollow/` by default:
+
+```
+~/.gitfollow/
+├── snapshots.json  # Follower snapshots
+└── history.json    # Change history
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/bulletdev/gitfollow.git
+cd gitfollow
+bundle install
+```
+
+### Run Tests
+
+```bash
+bundle exec rspec
+```
+
+### Lint Code
+
+```bash
+bundle exec rubocop
+```
+
+### Build Gem
+
+```bash
+gem build gitfollow.gemspec
+```
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please ensure:
+- All tests pass (`bundle exec rspec`)
+- Code follows style guide (`bundle exec rubocop`)
+- Add tests for new features
+- Update documentation as needed
+
+## Publishing to RubyGems
+
+### Manual Publication
+
+```bash
+# Build the gem
+gem build gitfollow.gemspec
+
+# Push to RubyGems
+gem push gitfollow-0.1.0.gem
+```
+
+### Automated Release
+
+1. Update version in `lib/gitfollow/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit changes
+4. Create and push a tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The GitHub Actions workflow will automatically build and publish to RubyGems.
+
+## Troubleshooting
+
+### Authentication Failed
+
+**Error:** `Authentication failed while fetching followers`
+
+**Solution:** Ensure your GitHub token is valid and has the required `read:user` scope.
+
+### Rate Limit Exceeded
+
+**Error:** `Rate limit exceeded`
+
+**Solution:** GitHub API has rate limits. Wait for the limit to reset or reduce check frequency.
+
+### No Changes Detected on First Run
+
+This is expected! Run `gitfollow init` first to create your initial snapshot.
+
+## Security
+
+- Never commit your GitHub token to version control
+- Use GitHub Secrets for CI/CD workflows
+- The `.env` file should be in `.gitignore`
+- Tokens are never logged or stored in data files
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [Octokit](https://github.com/octokit/octokit.rb) for GitHub API
+- Uses [Thor](https://github.com/rails/thor) for CLI framework
+- Formatted output with [TTY::Table](https://github.com/piotrmurach/tty-table)
+
+## Support
+
+- 🐛 [Report a bug](https://github.com/bulletdev/gitfollow/issues)
+- 💡 [Request a feature](https://github.com/bulletdev/gitfollow/issues)
+- 📖 [Documentation](https://github.com/bulletdev/gitfollow/blob/main/README.md)
+
+---
+
+**Made with  💎♦️ by [Michael D. Bullet](https://github.com/bulletdev)**
+
+⭐ Star this repo if you find it useful!

data/bin/gitfollow

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/gitfollow'
+
+begin
+  GitFollow::CLI.start(ARGV)
+rescue Interrupt
+  puts "\nInterrupted. Exiting..."
+  exit 130
+rescue StandardError => e
+  warn "Error: #{e.message}"
+  warn e.backtrace.join("\n") if ENV['DEBUG']
+  exit 1
+end