@bragduck/cli 1.0.3 → 2.0.1

package/README.md

@@ -1,15 +1,15 @@
 # Bragduck CLI
 
-> Transform your git commits into polished achievements with AI-powered refinement
+> Transform your GitHub Pull Requests into polished achievements with AI-powered refinement
 
 [![npm version](https://badge.fury.io/js/@bragduck%2Fcli.svg)](https://www.npmjs.com/package/@bragduck/cli)
 [![Node.js Version](https://img.shields.io/node/v/@bragduck/cli)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-122%20passing-brightgreen)](https://github.com/medhatdawoud/bragduck-cli)
+[![Tests](https://img.shields.io/badge/tests-126%20passing-brightgreen)](https://github.com/medhatdawoud/bragduck-cli)
 
 ## Overview
 
-Bragduck CLI is a powerful command-line tool that helps developers track and showcase their achievements by transforming git commits into polished "brags" using AI-powered refinement. Perfect for updating your portfolio, preparing for performance reviews, or simply keeping track of your accomplishments.
+Bragduck CLI is a powerful command-line tool that helps developers track and showcase their achievements by transforming GitHub Pull Requests into polished "brags" using AI-powered refinement. Perfect for updating your portfolio, preparing for performance reviews, or simply keeping track of your accomplishments.
 
 ### Why Bragduck?
 
@@ -20,6 +20,33 @@ Bragduck CLI is a powerful command-line tool that helps developers track and sho
 - 🚀 **Fast**: Optimized build size (69KB) for quick installation and execution
 - 🌐 **Cross-Platform**: Works on macOS, Windows, and Linux
 
+## Prerequisites
+
+Before installing Bragduck CLI, you need:
+
+1. **Node.js ≥18.0.0**
+   ```bash
+   node --version  # Should be v18.0.0 or higher
+   ```
+
+2. **GitHub CLI (gh)**
+   ```bash
+   # macOS
+   brew install gh
+
+   # Windows
+   winget install --id GitHub.cli
+
+   # Linux
+   # See https://github.com/cli/cli#installation
+   ```
+
+3. **Authenticate with GitHub CLI**
+   ```bash
+   gh auth login
+   ```
+   Follow the prompts to authenticate with your GitHub account.
+
 ## Installation
 
 ```bash
@@ -30,25 +57,34 @@ npm install -g @bragduck/cli
 
 ### Quick Start
 
-1. **Install globally:**
+1. **Install GitHub CLI and authenticate:**
+   ```bash
+   # Install GitHub CLI (if not already installed)
+   brew install gh  # macOS
+
+   # Authenticate with GitHub
+   gh auth login
+   ```
+
+2. **Install Bragduck CLI globally:**
    ```bash
    npm install -g @bragduck/cli
    ```
 
-2. **Initialize and authenticate:**
+3. **Initialize and authenticate:**
    ```bash
    bragduck init
    ```
    This opens your browser for OAuth authentication. Once completed, your credentials are securely stored.
 
-3. **Scan your commits:**
+4. **Scan your merged PRs:**
    ```bash
-   cd /path/to/your/git/repo
+   cd /path/to/your/github/repo
    bragduck scan
    ```
-   Select commits interactively, preview AI-refined brags, and create them.
+   Select PRs interactively, preview AI-refined brags, and create them.
 
-4. **View your brags:**
+5. **View your brags:**
    ```bash
    bragduck list
    ```
@@ -65,16 +101,16 @@ bragduck init
 
 #### `bragduck scan`
 
-Scan git commits and create brags with AI-powered refinement.
+Scan merged GitHub Pull Requests and create brags with AI-powered refinement.
 
 ```bash
-# Scan last 30 days (default)
+# Scan last 30 days (default, your PRs only)
 bragduck scan
 
 # Scan last 60 days
 bragduck scan --days 60
 
-# Include all commits (not just yours)
+# Include all PRs (not just yours)
 bragduck scan --all
 
 # Combine options
@@ -83,15 +119,28 @@ bragduck scan --days 90 --all
 
 **Options:**
 - `-d, --days <number>` - Number of days to scan (default: 30)
-- `-a, --all` - Include all commits, not just current user's
+- `-a, --all` - Include all PRs, not just current user's
 
 **Workflow:**
-1. Detects git repository
-2. Fetches recent commits
-3. Interactive checkbox selection
-4. AI refines selected commits
-5. Preview refined brags in table format
-6. Confirm and create brags
+1. Validates GitHub repository
+2. Fetches merged PRs in timeframe (filtered by author unless --all)
+3. Displays PRs in format: `#123 PR Title [stats]`
+4. Interactive checkbox selection
+5. AI refines selected PRs (using title + description)
+6. Preview refined brags in table format
+7. Confirm and create brags
+
+**What gets scanned:**
+- ✅ Merged Pull Requests only
+- ✅ PR title and description used for context
+- ✅ Aggregate PR statistics (files changed, insertions, deletions)
+- ✅ Filtered by PR author (person who created the PR)
+- ❌ Draft or closed-without-merge PRs excluded
+- ❌ Individual commits not scanned
+
+**Requirements:**
+- Must be in a GitHub repository (GitLab/Bitbucket not supported)
+- GitHub CLI must be installed and authenticated (`gh auth login`)
 
 #### `bragduck list`
 
@@ -132,20 +181,19 @@ Manage CLI configuration.
 bragduck config list
 
 # Get specific config value
-bragduck config get apiBaseUrl
 bragduck config get defaultCommitDays
 
 # Set config value
 bragduck config set defaultCommitDays 60
 bragduck config set autoVersionCheck false
-bragduck config set apiBaseUrl https://custom-api.example.com
 ```
 
 **Available Configuration Keys:**
-- `apiBaseUrl` - API base URL (default: https://api.bragduck.com)
 - `defaultCommitDays` - Default days to scan (1-365, default: 30)
 - `autoVersionCheck` - Automatic version checking (true/false, default: true)
 
+**Note:** The API base URL is set to `https://api.bragduck.com` by default. You can override it using the `API_BASE_URL` environment variable if needed for custom deployments.
+
 #### `bragduck logout`
 
 Clear stored credentials from your system.
@@ -196,6 +244,7 @@ bragduck --help
 - ✅ Windows (Compatible)
 - ✅ Linux (Compatible)
 - ✅ Node.js ≥18.0.0
+- ✅ GitHub repositories only (GitLab/Bitbucket not supported)
 
 ## Configuration
 
@@ -205,10 +254,11 @@ Configuration is stored in `~/.config/bragduck/config.json` (or equivalent on yo
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `apiBaseUrl` | string | `https://api.bragduck.com` | API base URL |
 | `defaultCommitDays` | number | `30` | Default days to scan (1-365) |
 | `autoVersionCheck` | boolean | `true` | Automatic version checking |
 
+**API Base URL:** The CLI connects to `https://api.bragduck.com` by default. For custom deployments, set the `API_BASE_URL` environment variable.
+
 ### Credentials Storage
 
 Credentials are encrypted and stored at:
@@ -241,17 +291,62 @@ git status  # Verify it's a git repo
 bragduck scan
 ```
 
-### No Commits Found
+### GitHub CLI Not Authenticated
+
+**Problem**: "Not authenticated with GitHub" error
+
+**Solution**:
+```bash
+# Authenticate with GitHub CLI
+gh auth login
+
+# Verify authentication
+gh auth status
+```
+
+### Not a GitHub Repository
 
-**Problem**: "No commits found in the last X days"
+**Problem**: "This repository is not hosted on GitHub" error
+
+**Solution**:
+- Bragduck CLI currently only supports GitHub repositories
+- Make sure you're in a repository with a GitHub remote:
+```bash
+git remote -v  # Should show github.com URL
+```
+
+### No Merged PRs Found
+
+**Problem**: "No merged PRs found in the last X days"
 
 **Solution**:
 ```bash
 # Increase the scan days
 bragduck scan --days 90
 
-# Or include all commits (not just yours)
+# Or include all PRs (not just yours)
 bragduck scan --all
+
+# Check if you have merged PRs on GitHub
+gh pr list --state merged --limit 10
+```
+
+### GitHub CLI Not Installed
+
+**Problem**: "GitHub CLI (gh) is not installed" error
+
+**Solution**:
+```bash
+# macOS
+brew install gh
+
+# Windows
+winget install --id GitHub.cli
+
+# Linux - see https://github.com/cli/cli#installation
+
+# Verify installation
+gh --version
 ```
 
 ### API Connection Issues
@@ -263,9 +358,6 @@ bragduck scan --all
 # Check your internet connection
 # Try with debug mode to see detailed logs
 bragduck --debug scan
-
-# Check if custom API URL is correct
-bragduck config get apiBaseUrl
 ```
 
 ### Version Check Failures
@@ -377,10 +469,10 @@ npx vitest
 ```
 
 **Test Stats:**
-- ✅ 122 tests passing
+- ✅ 126 tests passing
 - 📊 50% code coverage (focused on core logic)
-- 🧪 7 test suites covering:
-  - Services (Storage, Git, API)
+- 🧪 8 test suites covering:
+  - Services (Storage, Git, API, GitHub)
   - Commands (Config, List)
   - Utilities (Version, Errors)
 
@@ -398,6 +490,7 @@ src/
 │   ├── auth.service.ts     # Authentication & token management
 │   ├── api.service.ts      # Backend API client (ofetch)
 │   ├── git.service.ts      # Git operations (simple-git)
+│   ├── github.service.ts   # GitHub PR fetching (gh CLI)
 │   └── storage.service.ts  # Encrypted credential storage
 ├── ui/             # Terminal UI components
 │   ├── prompts.ts      # Interactive prompts (Inquirer)
@@ -432,6 +525,9 @@ src/
 - chalk, ora, cli-table3, boxen (terminal styling)
 - conf (configuration management)
 
+**External Tools:**
+- GitHub CLI (gh) - Required for PR scanning
+
 ## Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
@@ -457,7 +553,7 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gui
 
 ### Getting Help
 
-- 📖 **Documentation**: Read this README and [PLAN.md](PLAN.md)
+- 📖 **Documentation**: Read this README and [TESTING_GUIDE.md](TESTING_GUIDE.md)
 - 🐛 **Issues**: [GitHub Issues](https://github.com/medhatdawoud/bragduck-cli/issues)
 - 💬 **Discussions**: [GitHub Discussions](https://github.com/medhatdawoud/bragduck-cli/discussions)