@bragduck/cli 1.0.1 → 2.0.0

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`
 
@@ -196,6 +245,7 @@ bragduck --help
 - ✅ Windows (Compatible)
 - ✅ Linux (Compatible)
 - ✅ Node.js ≥18.0.0
+- ✅ GitHub repositories only (GitLab/Bitbucket not supported)
 
 ## Configuration
 
@@ -241,17 +291,62 @@ git status  # Verify it's a git repo
 bragduck scan
 ```
 
-### No Commits Found
+### GitHub CLI Not Authenticated
 
-**Problem**: "No commits found in the last X days"
+**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**: "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
@@ -377,10 +472,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 +493,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 +528,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 +556,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)
 

package/dist/bin/bragduck.js

@@ -308,7 +308,7 @@ var init_storage_service = __esm({
 });
 
 // src/utils/errors.ts
-var BragduckError, AuthenticationError, GitError, ApiError, NetworkError, ValidationError, OAuthError, TokenExpiredError;
+var BragduckError, AuthenticationError, GitError, ApiError, NetworkError, ValidationError, OAuthError, TokenExpiredError, GitHubError;
 var init_errors = __esm({
   "src/utils/errors.ts"() {
     "use strict";
@@ -366,6 +366,12 @@ var init_errors = __esm({
         this.code = "TOKEN_EXPIRED";
       }
     };
+    GitHubError = class extends BragduckError {
+      constructor(message, details) {
+        super(message, "GITHUB_ERROR", details);
+        this.name = "GitHubError";
+      }
+    };
   }
 });
 
@@ -1399,6 +1405,13 @@ init_esm_shims();
 import boxen4 from "boxen";
 import chalk7 from "chalk";
 
+// src/services/github.service.ts
+init_esm_shims();
+init_errors();
+init_logger();
+import { exec as exec2 } from "child_process";
+import { promisify as promisify2 } from "util";
+
 // src/services/git.service.ts
 init_esm_shims();
 import simpleGit from "simple-git";
@@ -1481,7 +1494,7 @@ var GitService = class {
    * Fetch recent commits
    */
   async getRecentCommits(options = {}) {
-    const { days = 30, limit, author, branch } = options;
+    const { days = 30, limit, author } = options;
     try {
       await this.validateRepository();
       logger.debug(`Fetching commits from last ${days} days`);
@@ -1619,6 +1632,203 @@ var GitService = class {
 };
 var gitService = new GitService();
 
+// src/services/github.service.ts
+var execAsync2 = promisify2(exec2);
+var GitHubService = class {
+  MAX_BODY_LENGTH = 5e3;
+  PR_SEARCH_FIELDS = "number,title,body,author,mergedAt,additions,deletions,changedFiles,url,labels";
+  /**
+   * Check if GitHub CLI is installed and available
+   */
+  async checkGitHubCLI() {
+    try {
+      await execAsync2("command gh --version");
+      return true;
+    } catch (_error) {
+      return false;
+    }
+  }
+  /**
+   * Validate that GitHub CLI is installed
+   */
+  async ensureGitHubCLI() {
+    const isInstalled = await this.checkGitHubCLI();
+    if (!isInstalled) {
+      throw new GitHubError("GitHub CLI (gh) is not installed", {
+        hint: "Install from https://cli.github.com/"
+      });
+    }
+  }
+  /**
+   * Check if user is authenticated with GitHub CLI
+   */
+  async checkAuthentication() {
+    try {
+      await execAsync2("command gh auth status");
+      return true;
+    } catch (_error) {
+      return false;
+    }
+  }
+  /**
+   * Ensure user is authenticated with GitHub CLI
+   */
+  async ensureAuthentication() {
+    const isAuthenticated = await this.checkAuthentication();
+    if (!isAuthenticated) {
+      throw new GitHubError("Not authenticated with GitHub", {
+        hint: 'Run "gh auth login" to authenticate'
+      });
+    }
+  }
+  /**
+   * Validate that the current repository is hosted on GitHub
+   */
+  async validateGitHubRepository() {
+    try {
+      await this.ensureGitHubCLI();
+      await this.ensureAuthentication();
+      await gitService.validateRepository();
+      const { stdout } = await execAsync2("command gh repo view --json url");
+      const data = JSON.parse(stdout);
+      if (!data.url) {
+        throw new GitHubError("This repository is not hosted on GitHub", {
+          hint: "Only GitHub repositories are currently supported for PR scanning"
+        });
+      }
+    } catch (error) {
+      if (error instanceof GitHubError || error instanceof GitError) {
+        throw error;
+      }
+      if (error.message?.includes("not a git repository")) {
+        throw new GitHubError("Not a git repository", {
+          hint: "Navigate to a git repository directory"
+        });
+      }
+      if (error.message?.includes("Could not resolve to a Repository")) {
+        throw new GitHubError("This repository is not hosted on GitHub", {
+          hint: "Only GitHub repositories are currently supported for PR scanning"
+        });
+      }
+      throw new GitHubError("Failed to validate GitHub repository", {
+        originalError: error.message
+      });
+    }
+  }
+  /**
+   * Get GitHub repository information
+   */
+  async getRepositoryInfo() {
+    try {
+      await this.ensureGitHubCLI();
+      const { stdout } = await execAsync2(
+        "command gh repo view --json owner,name,url,nameWithOwner"
+      );
+      const data = JSON.parse(stdout);
+      return {
+        owner: data.owner.login,
+        name: data.name,
+        fullName: data.nameWithOwner,
+        url: data.url,
+        isGitHub: true
+      };
+    } catch (error) {
+      if (error instanceof GitHubError || error instanceof GitError) {
+        throw error;
+      }
+      throw new GitHubError("Failed to get GitHub repository information", {
+        originalError: error.message
+      });
+    }
+  }
+  /**
+   * Get the current authenticated GitHub user
+   */
+  async getCurrentGitHubUser() {
+    try {
+      const { stdout } = await execAsync2("command gh api user --jq .login");
+      return stdout.trim() || null;
+    } catch (_error) {
+      logger.debug("Failed to get GitHub user");
+      return null;
+    }
+  }
+  /**
+   * Fetch merged PRs from GitHub
+   */
+  async getMergedPRs(options = {}) {
+    const { days = 30, limit, author } = options;
+    try {
+      await this.ensureGitHubCLI();
+      await this.ensureAuthentication();
+      logger.debug(`Fetching merged PRs from the last ${days} days`);
+      const since = /* @__PURE__ */ new Date();
+      since.setDate(since.getDate() - days);
+      const sinceDate = since.toISOString().split("T")[0];
+      let searchQuery = `merged:>=${sinceDate}`;
+      if (author) {
+        searchQuery += ` author:${author}`;
+      }
+      const limitArg = limit ? `--limit ${limit}` : "";
+      const command = `command gh pr list --state merged --json ${this.PR_SEARCH_FIELDS} --search "${searchQuery}" ${limitArg}`;
+      logger.debug(`Running: ${command}`);
+      const { stdout } = await execAsync2(command);
+      const prs = JSON.parse(stdout);
+      logger.debug(`Found ${prs.length} merged PRs`);
+      return prs;
+    } catch (error) {
+      if (error instanceof GitHubError || error instanceof GitError) {
+        throw error;
+      }
+      throw new GitHubError("Failed to fetch PRs from GitHub", {
+        originalError: error.message,
+        days
+      });
+    }
+  }
+  /**
+   * Get merged PRs by current user (PRs authored by the current user)
+   */
+  async getPRsByCurrentUser(options = {}) {
+    const currentUser = await this.getCurrentGitHubUser();
+    if (!currentUser) {
+      logger.warning("Could not determine GitHub user, returning all PRs");
+      return this.getMergedPRs(options);
+    }
+    logger.debug(`Filtering PRs by author: ${currentUser}`);
+    return this.getMergedPRs({
+      ...options,
+      author: currentUser
+    });
+  }
+  /**
+   * Transform a GitHub PR into a GitCommit structure
+   * This allows PR data to work with existing commit-based UI and API
+   */
+  transformPRToCommit(pr) {
+    const title = pr.title;
+    const body = pr.body || "";
+    const truncatedBody = body.length > this.MAX_BODY_LENGTH ? body.substring(0, this.MAX_BODY_LENGTH) + "...[truncated]" : body;
+    const message = truncatedBody ? `${title}
+
+${truncatedBody}` : title;
+    return {
+      sha: `pr-${pr.number}`,
+      message,
+      author: pr.author.login,
+      authorEmail: "",
+      // Not available from gh PR API
+      date: pr.mergedAt,
+      diffStats: {
+        filesChanged: pr.changedFiles,
+        insertions: pr.additions,
+        deletions: pr.deletions
+      }
+    };
+  }
+};
+var githubService = new GitHubService();
+
 // src/commands/scan.ts
 init_api_service();
 init_auth_service();
@@ -1633,8 +1843,15 @@ import { checkbox, confirm as confirm2, input, select } from "@inquirer/prompts"
 init_esm_shims();
 import chalk5 from "chalk";
 import Table from "cli-table3";
+import terminalLink from "terminal-link";
 function formatCommitChoice(commit) {
-  const sha = chalk5.yellow(commit.sha.substring(0, 7));
+  let displaySha;
+  if (commit.sha.startsWith("pr-")) {
+    const prNumber = commit.sha.replace("pr-", "#");
+    displaySha = chalk5.yellow(prNumber);
+  } else {
+    displaySha = chalk5.yellow(commit.sha.substring(0, 7));
+  }
   const message = commit.message.split("\n")[0];
   const author = chalk5.gray(`by ${commit.author}`);
   const date = chalk5.gray(new Date(commit.date).toLocaleDateString());
@@ -1645,7 +1862,7 @@ function formatCommitChoice(commit) {
       ` [${filesChanged} files, ${chalk5.green(`+${insertions}`)} ${chalk5.red(`-${deletions}`)}]`
     );
   }
-  return `${sha} ${message}${stats}
+  return `${displaySha} ${message}${stats}
     ${author} \u2022 ${date}`;
 }
 function formatRefinedCommitsTable(commits) {
@@ -1688,10 +1905,17 @@ function formatCommitStats(commits) {
 }
 function formatSuccessMessage(count) {
   const emoji = "\u{1F389}";
-  const title = chalk5.green.bold(`${emoji} Successfully created ${count} brag${count > 1 ? "s" : ""}!`);
+  const title = chalk5.green.bold(
+    `${emoji} Successfully created ${count} brag${count > 1 ? "s" : ""}!`
+  );
   const message = chalk5.white("\nYour achievements are now saved and ready to showcase.");
   const hint = chalk5.dim("\nRun ") + chalk5.cyan("bragduck list") + chalk5.dim(" to see all your brags");
-  return `${title}${message}${hint}`;
+  const url = "https://app.bragduck.com/brags";
+  const clickableUrl = terminalLink(url, url, {
+    fallback: () => chalk5.blue.underline(url)
+  });
+  const webUrl = chalk5.dim("\n\nOr, check ") + clickableUrl + chalk5.dim(" to see all your brags");
+  return `${title}${message}${hint}${webUrl}`;
 }
 function formatErrorMessage(message, hint) {
   const title = chalk5.red.bold("\u2717 Error");
@@ -1713,7 +1937,7 @@ async function promptSelectCommits(commits) {
     checked: false
   }));
   const selected = await checkbox({
-    message: "Select commits to brag about (use space to select, enter to confirm):",
+    message: "Select PRs to brag about (use space to select, enter to confirm):",
     choices,
     pageSize: 10,
     loop: false
@@ -1735,7 +1959,7 @@ async function promptDaysToScan(defaultDays = 30) {
     { name: "Custom", value: "custom", description: "Enter custom number of days" }
   ];
   const selected = await select({
-    message: "How many days back should we scan for commits?",
+    message: "How many days back should we scan for PRs?",
     choices,
     default: "30"
   });
@@ -1767,8 +1991,8 @@ function createSpinner(text) {
     spinner: "dots"
   });
 }
-function fetchingCommitsSpinner(days) {
-  return createSpinner(`Fetching commits from the last ${days} days...`);
+function fetchingPRsSpinner(days) {
+  return createSpinner(`Fetching merged PRs from the last ${days} days...`);
 }
 function refiningCommitsSpinner(count) {
   return createSpinner(`Refining ${count} commit${count > 1 ? "s" : ""} with AI...`);
@@ -1815,9 +2039,9 @@ Please run ${chalk7.cyan("bragduck init")} to login first.`,
       );
       process.exit(1);
     }
-    await gitService.validateRepository();
-    const repoInfo = await gitService.getRepositoryInfo();
-    logger.info(`Repository: ${chalk7.cyan(repoInfo.currentBranch)} branch`);
+    await githubService.validateGitHubRepository();
+    const repoInfo = await githubService.getRepositoryInfo();
+    logger.info(`Repository: ${chalk7.cyan(repoInfo.fullName)} on GitHub`);
     logger.log("");
     let days = options.days;
     if (!days) {
@@ -1825,21 +2049,22 @@ Please run ${chalk7.cyan("bragduck init")} to login first.`,
       days = await promptDaysToScan(defaultDays);
       logger.log("");
     }
-    const spinner = fetchingCommitsSpinner(days);
+    const spinner = fetchingPRsSpinner(days);
     spinner.start();
-    let commits;
+    let prs;
     if (options.all) {
-      commits = await gitService.getCommitsWithStats({ days });
+      prs = await githubService.getMergedPRs({ days });
     } else {
-      commits = await gitService.getCommitsByCurrentUser({ days });
+      prs = await githubService.getPRsByCurrentUser({ days });
     }
+    const commits = prs.map((pr) => githubService.transformPRToCommit(pr));
     if (commits.length === 0) {
-      failSpinner(spinner, `No commits found in the last ${days} days`);
+      failSpinner(spinner, `No merged PRs found in the last ${days} days`);
       logger.log("");
-      logger.info("Try increasing the number of days or check your git configuration");
+      logger.info("Try increasing the number of days or check your GitHub activity");
       return;
     }
-    succeedSpinner(spinner, `Found ${commits.length} commit${commits.length > 1 ? "s" : ""}`);
+    succeedSpinner(spinner, `Found ${commits.length} PR${commits.length > 1 ? "s" : ""}`);
     logger.log("");
     logger.log(formatCommitStats(commits));
     logger.log("");
@@ -1850,7 +2075,7 @@ Please run ${chalk7.cyan("bragduck init")} to login first.`,
     }
     const selectedCommits = commits.filter((c) => selectedShas.includes(c.sha));
     logger.log("");
-    logger.success(`Selected ${selectedCommits.length} commit${selectedCommits.length > 1 ? "s" : ""}`);
+    logger.success(`Selected ${selectedCommits.length} PR${selectedCommits.length > 1 ? "s" : ""}`);
     logger.log("");
     const refineSpinner = refiningCommitsSpinner(selectedCommits.length);
     refineSpinner.start();
@@ -1869,7 +2094,7 @@ Please run ${chalk7.cyan("bragduck init")} to login first.`,
     };
     const refineResponse = await apiService.refineCommits(refineRequest);
     const refinedCommits = refineResponse.refined_commits;
-    succeedSpinner(refineSpinner, "Commits refined successfully");
+    succeedSpinner(refineSpinner, "PRs refined successfully");
     logger.log("");
     logger.info("Preview of refined brags:");
     logger.log("");
@@ -1891,8 +2116,11 @@ Please run ${chalk7.cyan("bragduck init")} to login first.`,
           title: refined.refined_title,
           description: refined.refined_description,
           tags: refined.suggested_tags,
-          repository: repoInfo.remoteUrl,
-          date: originalCommit?.date || (/* @__PURE__ */ new Date()).toISOString()
+          repository: repoInfo.url,
+          date: originalCommit?.date || (/* @__PURE__ */ new Date()).toISOString(),
+          commit_url: refined.commit_url,
+          impact_score: refined.impact_score,
+          impact_description: refined.impact_description
         };
       })
     };
@@ -1922,8 +2150,11 @@ Please run ${chalk7.cyan("bragduck init")} to login first.`,
   }
 }
 function getErrorHint2(error) {
+  if (error.name === "GitHubError") {
+    return 'Make sure you are in a GitHub repository and have authenticated with "gh auth login"';
+  }
   if (error.name === "GitError") {
-    return "Make sure you are in a git repository with commits";
+    return "Make sure you are in a git repository. Note: Only GitHub repositories are supported for PR scanning.";
   }
   if (error.name === "TokenExpiredError" || error.name === "AuthenticationError") {
     return 'Run "bragduck init" to login again';