git-cleanup-merged 1.0.1

package/README.md

@@ -0,0 +1,473 @@
+# Git Cleanup Merged
+
+[![CI](https://github.com/ondrovic/git-cleanup-merged/actions/workflows/ci.yml/badge.svg)](https://github.com/ondrovic/git-cleanup-merged/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/ondrovic/git-cleanup-merged/graph/badge.svg?token=x3cYga3d2E)](https://codecov.io/gh/ondrovic/git-cleanup-merged)
+
+A Node.js command-line tool that automatically identifies and deletes local Git branches that have been merged via GitHub Pull Requests.
+
+---
+
+## 🧪 Testing & Quality Assurance
+
+- [![CI](https://github.com/ondrovic/git-cleanup-merged/actions/workflows/ci.yml/badge.svg)](https://github.com/ondrovic/git-cleanup-merged/actions/workflows/ci.yml) **CI runs on all pull requests and on push to `main`/`master` only** via GitHub Actions (tests Node.js 18.x, 20.x)
+  - This avoids duplicate runs for feature branches and is the recommended best practice for open source projects.
+- [![codecov](https://codecov.io/gh/ondrovic/git-cleanup-merged/graph/badge.svg?token=x3cYga3d2E)](https://codecov.io/gh/ondrovic/git-cleanup-merged) **Live coverage tracking** via Codecov
+- 🚦 **Branch coverage threshold:** CI will fail if branch coverage drops below 75%
+- 📝 **JUnit test results and coverage are uploaded to Codecov for every CI run**
+- 🧪 **Run tests locally:**
+  ```bash
+  npm test
+  npm run test:coverage
+  ```
+- 📈 **Check coverage report:**
+  After running `npm run test:coverage`, open `coverage/lcov-report/index.html` in your browser for a detailed report.
+- 🔍 **Code quality:** ESLint and Prettier configured for consistent code style
+
+---
+
+## ✨ Features
+
+- 🔍 **Smart Detection**: Automatically checks GitHub PR status for tracked branches
+- 🏷️ **Untracked Branch Support**: Clean up local-only branches with `--untracked-only` mode
+- ✅ **Safe Deletion**: Only deletes branches with merged or closed PRs, or untracked branches
+- 🔒 **Protection**: Never deletes `main`, `master`, or your current branch
+- 👀 **Preview Mode**: Dry-run option to see what would be deleted
+- 📂 **Directory Support**: Operate on any git repo by passing a directory as the first argument
+- 🎨 **Colorful Output**: Clear visual indicators with icons and colors
+- 📊 **Status Overview**: Shows comprehensive branch status table
+- ⚡ **Interactive Spinner**: Real-time progress updates with animated spinner
+- 🛡️ **Comprehensive Testing**: 100% test coverage with 97 test cases and live coverage tracking
+- 🎯 **Code Quality**: ESLint and Prettier for consistent code style
+- 🧠 **Smart UX**: Focused modes - main mode for PR cleanup, untracked mode for local cleanup
+
+## Prerequisites
+
+Before installing, make sure you have:
+
+- **Node.js** (version 18 or higher - tested on 18.x and 20.x)
+- **Git** installed and configured
+- **GitHub CLI** (`gh`) installed and authenticated (only required for main mode, not for `--untracked-only`)
+- Active internet connection for GitHub API calls (only required for main mode)
+
+### Installing GitHub CLI
+
+If you don't have GitHub CLI installed:
+
+**macOS (Homebrew):**
+
+```bash
+brew install gh
+```
+
+**Windows (Chocolatey):**
+
+```bash
+choco install gh
+```
+
+**Linux (Ubuntu/Debian):**
+
+```bash
+curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+sudo apt update
+sudo apt install gh
+```
+
+**Authenticate GitHub CLI:**
+
+```bash
+gh auth login
+```
+
+## Installation
+
+### Option 1: Global Installation via NPM
+
+```bash
+# Install globally from npm (if published)
+npm install -g git-cleanup-merged
+
+# Or install globally from GitHub
+npm install -g https://github.com/ondro/git-cleanup-merged.git
+```
+
+### Option 2: Local Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/ondro/git-cleanup-merged.git
+cd git-cleanup-merged
+
+# Install dependencies
+npm install
+
+# Make executable (Unix/macOS/Linux)
+chmod +x index.js
+
+# Create symlink for global access (optional)
+npm link
+```
+
+### Option 3: Direct Download
+
+```bash
+# Download the script directly
+curl -o git-cleanup-merged https://raw.githubusercontent.com/ondro/git-cleanup-merged/main/index.js
+chmod +x git-cleanup-merged
+
+# Move to your PATH
+sudo mv git-cleanup-merged /usr/local/bin/
+```
+
+### Option 4: Using npx (No Installation)
+
+```bash
+# Run directly without installing
+npx git-cleanup-merged
+
+# Or from GitHub
+npx https://github.com/ondro/git-cleanup-merged.git
+```
+
+## Usage
+
+### Basic Usage
+
+> **Note:** At the start of every run, the tool will display the name of the repository directory being scanned (e.g. 'git-local-branch-cleanup' or 'ollama-git-commit'), so you always know which directory is being operated on.
+
+#### Main Mode (Default) - Clean up branches with merged PRs
+
+```bash
+# Clean up merged branches (with confirmation)
+git-cleanup-merged
+
+# Clean up merged branches in a different directory
+git-cleanup-merged ../path/to/repo
+
+# Preview what would be deleted (dry run)
+git-cleanup-merged --dry-run
+
+# Show detailed processing information
+git-cleanup-merged --verbose
+
+# Combine options
+git-cleanup-merged ../path/to/repo --dry-run --verbose
+```
+
+#### Untracked Mode - Clean up local-only branches
+
+```bash
+# Clean up untracked branches (local branches without remote tracking)
+git-cleanup-merged --untracked-only
+
+# Same as above using shorthand
+git-cleanup-merged -u
+
+# Preview untracked branches (dry run)
+git-cleanup-merged --untracked-only --dry-run
+
+# Same as above using shorthand
+git-cleanup-merged -u -n
+
+# Show detailed processing for untracked branches
+git-cleanup-merged --untracked-only --verbose
+
+# Same as above using shorthand
+git-cleanup-merged -u -v
+
+# Clean up untracked branches in a different directory
+git-cleanup-merged ../path/to/repo --untracked-only
+
+# Same as above using shorthand
+git-cleanup-merged ../path/to/repo -u
+```
+
+### Command Line Options
+
+| Option             | Short | Description                                                                          |
+| ------------------ | ----- | ------------------------------------------------------------------------------------ |
+| `[DIRECTORY]`      |       | Path to a git repository to operate on. Defaults to the current directory if omitted |
+| `--dry-run`        | `-n`  | Show what would be deleted without actually deleting                                 |
+| `--verbose`        | `-v`  | Show detailed information during processing                                          |
+| `--untracked-only` | `-u`  | Only process untracked local branches (no remote tracking branch)                    |
+| `--help`           | `-h`  | Show help message                                                                    |
+
+### Example Output
+
+#### Main Mode (Default) - Branches with merged PRs
+
+```
+📂 Scanning repository: my-project
+✅ Dependencies checked
+✅ Current branch: main
+✅ Finished checking 3 tracked branches
+
+────────────────────────────────────────────────────────────
+Branch                                   Icon   Status
+────────────────────────────────────────────────────────────
+feature/user-authentication              ✅     Merged
+bugfix/header-layout                     ✅     Merged
+feature/experimental                     🔒     Closed
+feature/dark-mode                        ⏳     Open
+────────────────────────────────────────────────────────────
+
+❌ The following branches have merged or closed PRs and will be deleted:
+  feature/user-authentication
+  bugfix/header-layout
+  feature/experimental
+
+Proceed with deletion? (y/N): y
+
+✅ Deleted branch feature/user-authentication
+✅ Deleted branch bugfix/header-layout
+✅ Deleted branch feature/experimental
+✅ Successfully deleted 3 branches
+```
+
+#### Untracked Mode - Local-only branches
+
+```
+📂 Scanning repository: my-project
+✅ Dependencies checked
+✅ Current branch: main
+✅ Finished processing 2 untracked branches
+
+────────────────────────────────────────────────────────────
+Branch                                   Icon   Status
+────────────────────────────────────────────────────────────
+debug/test-branch                        🏷️    Untracked
+temp/experiment                          🏷️    Untracked
+────────────────────────────────────────────────────────────
+
+❌ The following untracked local branches will be deleted:
+  debug/test-branch
+  temp/experiment
+
+Proceed with deletion of untracked branches? (y/N): y
+
+✅ Deleted branch debug/test-branch
+✅ Deleted branch temp/experiment
+✅ Successfully deleted 2 branches
+```
+
+## How It Works
+
+### Main Mode (Default)
+
+1. **Dependency Check**: Verifies you're in a Git repository and GitHub CLI is installed/authenticated
+2. **Current Branch Detection**: Identifies and protects your current working branch
+3. **Tracked Branch Discovery**: Lists only branches that have remote tracking (excluding `main`, `master`, current branch)
+   - Uses Git's upstream tracking information to accurately detect tracked branches
+   - Works with any remote name (origin, upstream, etc.) - not hard-coded to "origin"
+   - Robust parsing handles multiple consecutive spaces in Git output
+4. **PR Status Check**: Queries GitHub API for each branch's PR status with progress indication
+5. **Results Display**: Shows a comprehensive status table with clear visual indicators
+6. **Safe Deletion**: Only deletes branches with merged or closed PRs (with user confirmation)
+
+### Untracked Mode (`--untracked-only`)
+
+1. **Dependency Check**: Verifies you're in a Git repository (GitHub CLI not required)
+2. **Current Branch Detection**: Identifies and protects your current working branch
+3. **Untracked Branch Discovery**: Lists only local branches without remote tracking (excluding `main`, `master`, current branch)
+   - Uses Git's upstream tracking information to accurately detect untracked branches
+   - Works with any remote name (origin, upstream, etc.) - not hard-coded to "origin"
+   - Robust parsing handles multiple consecutive spaces in Git output
+4. **Results Display**: Shows untracked branches with 🏷️ icon
+5. **Safe Deletion**: Deletes untracked branches (with user confirmation)
+
+## Branch Status Indicators
+
+### Main Mode
+
+| Icon | Status | Description                                            |
+| ---- | ------ | ------------------------------------------------------ |
+| ✅   | Merged | PR has been merged - branch is safe to delete          |
+| 🔒   | Closed | PR has been closed without merging - branch is safe to delete |
+| ⏳   | Open   | PR is still open - branch will be preserved            |
+| ❌   | No PR  | No PR found for this branch - branch will be preserved |
+
+### Untracked Mode
+
+| Icon | Status    | Description                                           |
+| ---- | --------- | ----------------------------------------------------- |
+| 🏷️   | Untracked | Local branch without remote tracking - safe to delete |
+
+## Safety Features
+
+- **Protected Branches**: Never touches `main`, `master`, or your current branch
+- **Confirmation Required**: Always asks before deleting (unless in dry-run mode)
+- **GitHub Verification**: Only deletes branches with confirmed merged or closed PRs (main mode)
+- **Untracked Detection**: Only deletes local branches without remote tracking (untracked mode)
+- **Robust Parsing**: Handles various Git output formats including multiple consecutive spaces
+- **Error Handling**: Graceful failure handling with informative messages
+- **Progress Feedback**: Real-time spinner shows current operation status
+- **Smart UX**: Main mode focuses on PR cleanup, untracked mode focuses on local cleanup
+
+## Troubleshooting
+
+### Common Issues
+
+**"Not in a git repository"**
+
+- Make sure you're running the command from within a Git repository
+
+**"GitHub CLI (gh) is not installed"**
+
+- Install GitHub CLI following the prerequisites section above
+
+**"GitHub CLI is not authenticated"**
+
+- Run `gh auth login` and follow the authentication process
+
+**"Failed to get current branch"**
+
+- Ensure you're in a valid Git repository with at least one commit
+
+**Branch names appearing garbled in terminal**
+
+- This was a known issue with the spinner display that has been fixed in recent versions
+
+### Debug Mode
+
+For troubleshooting, use verbose mode to see detailed processing:
+
+```bash
+# Main mode with verbose output
+git-cleanup-merged --verbose --dry-run
+
+# Untracked mode with verbose output
+git-cleanup-merged --untracked-only --verbose --dry-run
+
+# Same as above using shorthand
+git-cleanup-merged -u -v -n
+```
+
+## Development
+
+### Project Structure
+
+```
+git-cleanup-merged/
+├── __tests__/              # Test files
+│   ├── index.test.js       # Main functionality tests
+│   ├── spinner.test.js     # Spinner component tests
+│   └── utils.test.js       # Utility function tests
+├── coverage/               # Coverage reports (generated)
+
+├── src/
+│   ├── bin.js              # CLI entry point
+│   ├── index.js            # Main GitCleanupTool class
+│   └── utils/
+│       ├── index.js        # Utility functions
+│       └── spinner.js      # Spinner component
+├── package.json
+├── package-lock.json
+├── eslint.config.mjs      # ESLint configuration
+├── .prettierrc            # Prettier configuration
+└── README.md
+```
+
+### Key Components
+
+- **GitCleanupTool**: Main class that orchestrates the cleanup process
+- **Spinner**: Enhanced spinner class with proper terminal handling and testability
+- **CLI Entry Point**: Separate `bin.js` file for clean CLI execution
+- **Test Suite**: Comprehensive tests covering all functionality and edge cases
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly with both `--dry-run` and actual deletion
+5. Submit a pull request
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run linting
+npm run lint
+
+# Run linting with auto-fix
+npm run lint -- --fix
+
+# Format code
+npm run format
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## 📋 Changelog
+
+### v1.3.1
+
+- 🐛 **Critical Bug Fix**: Fixed whitespace parsing issue in branch tracking detection
+  - The `line.split(" ")` logic was not robust and could misclassify tracked branches as untracked when `git for-each-ref` output contained multiple consecutive spaces
+  - Replaced with `line.split(/\s+/)` and proper array handling to correctly parse branch names and upstream information
+  - Added comprehensive tests to verify the fix works with various whitespace scenarios
+- 🧪 **Enhanced Testing**: Added 2 new test cases specifically for whitespace parsing edge cases
+- ✅ **Maintained Quality**: 100% test coverage preserved with 97 test cases
+
+### v1.3.0
+
+- 🏷️ **New Feature**: Added `--untracked-only` mode to clean up local branches without remote tracking
+- 🧠 **Improved UX**: Main mode now only shows tracked branches with PRs, untracked mode handles local-only branches
+- 🔧 **Smart Dependencies**: GitHub CLI only required for main mode, not for untracked mode
+- 💡 **Helpful Guidance**: Suggests `--untracked-only` when no tracked branches found in main mode
+- 🎯 **100% Test Coverage**: Achieved complete test coverage with 97 comprehensive test cases
+- 🐛 **Bug Fixes**: Fixed branch tracking detection logic and improved deletion feedback
+- 📊 **Enhanced Testing**: Added tests for all new functionality and edge cases
+- 🔧 **Critical Fix**: Fixed branch tracking detection to use proper Git upstream relationships instead of hard-coded remote names
+- 🛠️ **Robust Parsing**: Fixed whitespace parsing bug that could misclassify tracked branches as untracked
+
+### v1.2.1
+
+- 🔧 **Node.js Compatibility**: Updated to require Node.js 18+ for ESLint 9.x compatibility
+- 🧪 **CI Updates**: Removed Node.js 16.x from CI matrix (reached end-of-life)
+- 📦 **Dependencies**: Updated to use modern ESLint flat config format
+- 🚦 **Workflow Optimization**: CI now only runs on pull requests and on push to `main`/`master` to avoid duplicate runs for feature branches
+
+### v1.2.0
+
+- 🎯 **100% Test Coverage**: Achieved complete test coverage across all code paths
+- 🧪 **Enhanced Test Suite**: Added 76 comprehensive test cases covering all functionality
+- 🔧 **Code Quality**: Added ESLint and Prettier for consistent code style
+- 🏗️ **Architecture Improvements**: Separated CLI entry point for better testability
+- 🐛 **Bug Fixes**: Fixed spinner component and improved error handling
+- 📊 **Coverage Thresholds**: Set minimum 75% branch coverage requirement
+
+### v1.1.0
+
+- Fixed spinner display issue where branch names would merge together
+- Improved terminal output clearing with proper ANSI escape sequences
+- Enhanced progress indicators during branch checking and deletion
+- Added directory argument support for operating on different repositories
+
+### v1.0.0
+
+- Initial release
+- Basic branch cleanup functionality
+- GitHub PR integration
+- Dry-run mode
+- Verbose logging
+- Interactive spinner with progress feedback
+
+## 🤝 Support
+
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/ondro/git-cleanup-merged/issues)
+- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/ondro/git-cleanup-merged/discussions)
+- 📧 **Contact**: ondrovic@gmail.com
+- 📚 **Documentation**: This README contains comprehensive usage examples and troubleshooting
+
+---
+
+**⚠️ Important**: Always run with `--dry-run` first to preview changes before actual deletion. This tool is designed to be safe, but you should always verify the branches it wants to delete.

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "git-cleanup-merged",
+  "version": "1.0.1",
+  "description": "Clean up local Git branches that have merged PRs on GitHub",
+  "main": "index.js",
+  "bin": {
+    "git-cleanup-merged": "./src/bin.js"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "test:coverage:ci": "jest --coverage && node scripts/fix-junit.js",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "git",
+    "github",
+    "cli",
+    "cleanup",
+    "branches",
+    "merge"
+  ],
+  "author": "Chris Ondrovic",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "preferGlobal": true,
+  "files": [
+    "src/**/*.js",
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ondro/git-cleanup-merged.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ondro/git-cleanup-merged/issues"
+  },
+  "homepage": "https://github.com/ondro/git-cleanup-merged#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.30.1",
+    "eslint": "^9.30.1",
+    "globals": "^16.3.0",
+    "jest": "^30.0.3",
+    "jest-junit": "^16.0.0",
+    "prettier": "^3.6.2"
+  },
+  "jest": {
+    "coverageThreshold": {
+      "global": {
+        "branches": 75
+      }
+    },
+    "collectCoverageFrom": [
+      "src/**/*.js",
+      "!src/bin.js"
+    ],
+    "coverageReporters": [
+      "text",
+      "lcov",
+      "html"
+    ],
+    "reporters": [
+      "default",
+      [
+        "jest-junit",
+        {
+          "outputDirectory": "coverage",
+          "outputName": "junit.xml",
+          "classNameTemplate": "{filepath}",
+          "titleTemplate": "{title}",
+          "ancestorSeparator": " › ",
+          "usePathForSuiteName": true,
+          "useFullFilePath": true,
+          "classNameTemplate": "{filepath}"
+        }
+      ]
+    ]
+  }
+}

package/src/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const GitCleanupTool = require("./index");
+
+const tool = new GitCleanupTool();
+const code = tool.parseArguments();
+if (typeof code === "number") process.exit(code);
+if (code === undefined) tool.run();

package/src/index.js

@@ -0,0 +1,605 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const readline = require("readline");
+const clearTerminal = require("./utils");
+const Spinner = require("./utils/spinner");
+const path = require("path");
+
+// Colors for terminal output
+const colors = {
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+};
+
+class GitCleanupTool {
+  constructor() {
+    this.dryRun = false;
+    this.verbose = false;
+    this.untrackedOnly = false;
+    this.countOnly = false;
+    this.branchesToDelete = [];
+    this.prResults = [];
+    this.currentBranch = "";
+    this.spinner = new Spinner();
+  }
+
+  // Helper method for minimum spinner visibility
+  async sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  async execCommand(command, options = {}) {
+    try {
+      const result = execSync(command, {
+        encoding: "utf8",
+        stdio: options.silent ? "pipe" : "inherit",
+        ...options,
+      });
+      return result.trim();
+    } catch (error) {
+      if (!options.silent) {
+        throw error;
+      }
+      return null;
+    }
+  }
+
+  async checkDependencies() {
+    this.spinner.updateMessage("Checking dependencies...");
+    this.spinner.start();
+
+    // Check if we're in a git repository
+    if (
+      (await this.execCommand("git rev-parse --git-dir", { silent: true })) ===
+      null
+    ) {
+      this.spinner.error("Not in a git repository");
+      process.exit(1);
+    }
+    await this.sleep(300); // Minimum spinner time
+
+    // Only check GitHub CLI dependencies if not in untracked-only or count-only mode
+    if (!this.untrackedOnly && !this.countOnly) {
+      this.spinner.updateMessage("Checking GitHub CLI...");
+      // Check for GitHub CLI
+      if ((await this.execCommand("gh --version", { silent: true })) === null) {
+        this.spinner.error(
+          "GitHub CLI (gh) is not installed. Please install it from https://cli.github.com/",
+        );
+        process.exit(1);
+      }
+      await this.sleep(200);
+
+      this.spinner.updateMessage("Verifying GitHub authentication...");
+      // Check GitHub CLI authentication
+      if (
+        (await this.execCommand("gh auth status", { silent: true })) === null
+      ) {
+        this.spinner.error(
+          "GitHub CLI is not authenticated. Run: gh auth login",
+        );
+        process.exit(1);
+      }
+      await this.sleep(200);
+    }
+
+    this.spinner.success("Dependencies checked");
+  }
+
+  async getCurrentBranch() {
+    this.spinner.updateMessage("Getting current branch...");
+    this.spinner.start();
+
+    try {
+      this.currentBranch = await this.execCommand("git branch --show-current", {
+        silent: true,
+      });
+      await this.sleep(200); // Let the spinner show
+      this.spinner.success(`Current branch: ${this.currentBranch}`);
+    } catch {
+      this.spinner.error("Failed to get current branch");
+      process.exit(1);
+    }
+  }
+
+  async getLocalBranches() {
+    try {
+      const branches = await this.execCommand(
+        'git for-each-ref --format="%(refname:short)" refs/heads/',
+        { silent: true },
+      );
+
+      return branches
+        .split("\n")
+        .filter((branch) => branch.trim() !== "")
+        .filter(
+          (branch) =>
+            !["main", "master", this.currentBranch].includes(branch.trim()),
+        )
+        .map((branch) => branch.trim());
+    } catch {
+      this.spinner.error("Failed to get local branches");
+      return [];
+    }
+  }
+
+  async getTrackedBranches() {
+    try {
+      // Get all local branches with their upstream tracking information
+      const branches = await this.execCommand(
+        'git for-each-ref --format="%(refname:short) %(upstream:short)" refs/heads/',
+        { silent: true },
+      );
+
+      const trackedBranches = [];
+
+      const branchLines = branches
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => line.trim());
+
+      for (const line of branchLines) {
+        // Use regex to split on one or more whitespace characters
+        const parts = line.split(/\s+/);
+        const branchName = parts[0];
+        const upstream = parts.slice(1).join(" "); // Join remaining parts in case upstream contains spaces
+
+        // Skip main, master, and current branch
+        if (["main", "master", this.currentBranch].includes(branchName)) {
+          continue;
+        }
+
+        // If upstream is not empty, the branch is tracking a remote branch
+        if (upstream && upstream.trim() !== "") {
+          trackedBranches.push(branchName);
+        }
+      }
+
+      return trackedBranches;
+    } catch {
+      this.spinner.error("Failed to get tracked branches");
+      return [];
+    }
+  }
+
+  async getUntrackedBranches() {
+    try {
+      // Get all local branches with their upstream tracking information
+      const branches = await this.execCommand(
+        'git for-each-ref --format="%(refname:short) %(upstream:short)" refs/heads/',
+        { silent: true },
+      );
+
+      const untrackedBranches = [];
+
+      const branchLines = branches
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => line.trim());
+
+      for (const line of branchLines) {
+        // Use regex to split on one or more whitespace characters
+        const parts = line.split(/\s+/);
+        const branchName = parts[0];
+        const upstream = parts.slice(1).join(" "); // Join remaining parts in case upstream contains spaces
+
+        // Skip main, master, and current branch
+        if (["main", "master", this.currentBranch].includes(branchName)) {
+          continue;
+        }
+
+        // If upstream is empty, the branch is not tracking any remote branch
+        if (!upstream || upstream.trim() === "") {
+          untrackedBranches.push(branchName);
+        }
+      }
+
+      return untrackedBranches;
+    } catch {
+      this.spinner.error("Failed to get untracked branches");
+      return [];
+    }
+  }
+
+  async countBranches() {
+    this.spinner.updateMessage("Counting branches...");
+    this.spinner.start();
+
+    const trackedBranches = await this.getTrackedBranches();
+    const untrackedBranches = await this.getUntrackedBranches();
+    const total = trackedBranches.length + untrackedBranches.length;
+
+    await this.sleep(300); // Minimum spinner time
+    this.spinner.success("Branch count complete");
+
+    console.log("");
+    console.log(`${colors.bold}📊 Branch Count Summary${colors.reset}`);
+    console.log(`  Total branches: ${total}`);
+    console.log(`  Tracked: ${trackedBranches.length}`);
+    console.log(`  Untracked: ${untrackedBranches.length}`);
+  }
+
+  async getPRStatus(branch) {
+    try {
+      const result = await this.execCommand(
+        `gh pr view "${branch}" --json state --jq .state`,
+        { silent: true },
+      );
+      return result;
+    } catch {
+      return null;
+    }
+  }
+
+  async checkBranches() {
+    this.spinner.updateMessage("Fetching tracked branches...");
+    this.spinner.start();
+
+    const branches = await this.getTrackedBranches();
+
+    if (branches.length === 0) {
+      this.spinner.warning("No tracked branches found to check.");
+      this.spinner.info(
+        "You might want to use --untracked-only to see local-only branches.",
+      );
+      return;
+    }
+
+    this.spinner.updateMessage(
+      `Checking ${branches.length} tracked branches against GitHub...`,
+    );
+
+    // Process each branch
+    for (let i = 0; i < branches.length; i++) {
+      const branch = branches[i];
+      this.spinner.updateMessage(
+        `Checking branch ${i + 1}/${branches.length}: ${branch}`,
+      );
+
+      const prStatus = await this.getPRStatus(branch);
+
+      // Only call debug if verbose is enabled to avoid stopping spinner
+      if (this.verbose) {
+        this.spinner.debug(
+          `Checking branch ${branch} -> PR state: ${prStatus || "unknown"}`,
+          this.verbose,
+        );
+        // Restart spinner after debug output
+        this.spinner.updateMessage(
+          `Checking branch ${i + 1}/${branches.length}: ${branch}`,
+        );
+        this.spinner.start();
+      }
+
+      let icon, label;
+      switch (prStatus) {
+        case "MERGED":
+          icon = "✅";
+          label = "Merged";
+          this.branchesToDelete.push(branch);
+          break;
+        case "CLOSED":
+          icon = "🔒";
+          label = "Closed";
+          this.branchesToDelete.push(branch);
+          break;
+        case "OPEN":
+          icon = "⏳";
+          label = "Open";
+          break;
+        default:
+          icon = "❌";
+          label = "No PR";
+          break;
+      }
+
+      this.prResults.push({ branch, icon, label });
+
+      // Add a small delay so we can see the spinner working
+      await this.sleep(300);
+    }
+
+    this.spinner.success(
+      `Finished checking ${branches.length} tracked branches`,
+    );
+    console.log(""); // Empty line for spacing
+  }
+
+  async checkUntrackedBranches() {
+    this.spinner.updateMessage("Fetching untracked local branches...");
+    this.spinner.start();
+
+    const untrackedBranches = await this.getUntrackedBranches();
+
+    if (untrackedBranches.length === 0) {
+      this.spinner.warning("No untracked local branches found.");
+      return;
+    }
+
+    this.spinner.updateMessage(
+      `Found ${untrackedBranches.length} untracked local branches...`,
+    );
+
+    // Process each untracked branch
+    for (let i = 0; i < untrackedBranches.length; i++) {
+      const branch = untrackedBranches[i];
+      this.spinner.updateMessage(
+        `Processing untracked branch ${i + 1}/${untrackedBranches.length}: ${branch}`,
+      );
+
+      // Only call debug if verbose is enabled to avoid stopping spinner
+      if (this.verbose) {
+        this.spinner.debug(
+          `Processing untracked branch ${branch}`,
+          this.verbose,
+        );
+        // Restart spinner after debug output
+        this.spinner.updateMessage(
+          `Processing untracked branch ${i + 1}/${untrackedBranches.length}: ${branch}`,
+        );
+        this.spinner.start();
+      }
+
+      const icon = "🏷️";
+      const label = "Untracked";
+      this.branchesToDelete.push(branch);
+
+      this.prResults.push({ branch, icon, label });
+
+      // Add a small delay so we can see the spinner working
+      await this.sleep(300);
+    }
+
+    this.spinner.success(
+      `Finished processing ${untrackedBranches.length} untracked branches`,
+    );
+    console.log(""); // Empty line for spacing
+  }
+
+  displayResults() {
+    this.spinner.log("─".repeat(60));
+    this.spinner.log(
+      `${"Branch".padEnd(40)} ${"Icon".padEnd(6)} ${"Status".padEnd(10)}`,
+    );
+    this.spinner.log("─".repeat(60));
+
+    this.prResults.forEach(({ branch, icon, label }) => {
+      this.spinner.log(
+        `${branch.padEnd(40)} ${icon.padEnd(6)} ${label.padEnd(10)}`,
+      );
+    });
+
+    this.spinner.log("─".repeat(60));
+  }
+
+  async deleteBranches() {
+    if (this.branchesToDelete.length === 0) {
+      if (this.untrackedOnly) {
+        this.spinner.warning("No untracked local branches found.");
+      } else {
+        this.spinner.warning("No branches with merged or closed PRs found.");
+      }
+      return;
+    }
+
+    console.log(""); // Empty line for spacing
+    if (this.dryRun) {
+      this.spinner.warning("DRY RUN — branches eligible for deletion:");
+    } else {
+      if (this.untrackedOnly) {
+        this.spinner.error(
+          "The following untracked local branches will be deleted:",
+        );
+      } else {
+        this.spinner.error(
+          "The following branches have merged or closed PRs and will be deleted:",
+        );
+      }
+    }
+
+    // List branches without icons since the spinner methods handle them
+    this.branchesToDelete.forEach((branch) => {
+      this.spinner.log(`  ${branch}`, colors.red);
+    });
+
+    if (this.dryRun) {
+      if (this.untrackedOnly) {
+        this.spinner.info(
+          "Run without --dry-run to actually delete untracked branches.",
+        );
+      } else {
+        this.spinner.info("Run without --dry-run to actually delete them.");
+      }
+      return;
+    }
+
+    const confirmationMessage = this.untrackedOnly
+      ? "Proceed with deletion of untracked branches? (y/N): "
+      : "Proceed with deletion? (y/N): ";
+
+    const confirmed = await this.askConfirmation(confirmationMessage);
+
+    if (confirmed) {
+      console.log(""); // Empty line for spacing
+
+      let deletedCount = 0;
+      let failedBranches = [];
+
+      for (let i = 0; i < this.branchesToDelete.length; i++) {
+        const branch = this.branchesToDelete[i];
+        this.spinner.updateMessage(
+          `Deleting branch ${i + 1}/${this.branchesToDelete.length}: ${branch}`,
+        );
+        this.spinner.start();
+
+        try {
+          await this.execCommand(`git branch -d "${branch}"`, { silent: true });
+          deletedCount++;
+          // Stop spinner before printing confirmation to avoid overlap
+          this.spinner.stop();
+          this.spinner.log(`✅ Deleted branch ${branch}`, colors.green);
+          // Brief pause to show progress
+          await this.sleep(200);
+        } catch {
+          failedBranches.push(branch);
+          // Stop spinner before printing error to avoid overlap
+          this.spinner.stop();
+          this.spinner.log(`❌ Failed to delete branch ${branch}`, colors.red);
+          await this.sleep(200);
+        }
+      }
+
+      // Final status
+      if (failedBranches.length === 0) {
+        this.spinner.success(`Successfully deleted ${deletedCount} branches`);
+      } else {
+        this.spinner.warning(
+          `Deleted ${deletedCount} branches, ${failedBranches.length} failed`,
+        );
+        failedBranches.forEach((branch) => {
+          this.spinner.log(`  Failed: ${branch}`, colors.red);
+        });
+      }
+    } else {
+      this.spinner.info("Cancelled.");
+    }
+  }
+
+  async askConfirmation(question) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+      rl.question(question, (answer) => {
+        rl.close();
+        resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+      });
+    });
+  }
+
+  showHelp() {
+    console.log(`
+${colors.bold}git-cleanup-merged${colors.reset} - Clean up merged Git branches
+
+${colors.bold}USAGE:${colors.reset}
+    git-cleanup-merged [DIRECTORY] [OPTIONS]
+
+${colors.bold}DIRECTORY (optional):${colors.reset}
+    Path to a git repository to operate on. Defaults to the current directory if omitted.
+
+${colors.bold}OPTIONS:${colors.reset}
+    -n, --dry-run         Show what would be deleted without actually deleting
+    -v, --verbose         Show detailed information during processing
+    -u, --untracked-only  Only process untracked local branches (no remote tracking branch)
+    -c, --count           Display branch count summary and exit (no deletion)
+    -h, --help            Show this help message
+
+${colors.bold}DESCRIPTION:${colors.reset}
+    This tool checks your local Git branches against GitHub PRs to find
+    branches that have been merged and are safe to delete locally.
+    
+    When using --untracked-only, it will only process local branches that
+    don't have a corresponding remote tracking branch.
+
+${colors.bold}REQUIREMENTS:${colors.reset}
+    - Git repository
+    - GitHub CLI (gh) installed and authenticated (only for normal mode)
+    - Internet connection to check GitHub PR status (only for normal mode)
+
+${colors.bold}EXAMPLES:${colors.reset}
+    git-cleanup-merged                    # Clean up merged branches in current directory
+    git-cleanup-merged ../my/repo         # Clean up merged branches in another repo
+    git-cleanup-merged --dry-run          # Preview what would be deleted
+    git-cleanup-merged --verbose          # Show detailed processing info
+    git-cleanup-merged --untracked-only   # Clean up untracked local branches only
+    git-cleanup-merged -u                 # Same as --untracked-only
+    git-cleanup-merged --untracked-only --dry-run  # Preview untracked branches
+    git-cleanup-merged -u -n              # Same as above with shorthand
+    git-cleanup-merged --count            # Display branch count summary
+    git-cleanup-merged -c                 # Same as --count
+        `);
+  }
+
+  parseArguments() {
+    const args = process.argv.slice(2);
+    // Check for a directory as the first positional argument (not a flag)
+    if (args[0] && !args[0].startsWith("-")) {
+      try {
+        process.chdir(args[0]);
+      } catch {
+        this.spinner.error(`Failed to change directory to: ${args[0]}`);
+        process.exit(1);
+      }
+      args.shift();
+    }
+    for (const arg of args) {
+      switch (arg) {
+        case "--dry-run":
+        case "-n":
+          this.dryRun = true;
+          break;
+        case "--verbose":
+        case "-v":
+          this.verbose = true;
+          break;
+        case "--untracked-only":
+        case "-u":
+          this.untrackedOnly = true;
+          break;
+        case "--count":
+        case "-c":
+          this.countOnly = true;
+          break;
+        case "--help":
+        case "-h":
+          this.showHelp();
+          return 0;
+        default:
+          this.spinner.error(`Unknown option: ${arg}`);
+          this.spinner.info("Use --help for usage information.");
+          process.exit(1);
+      }
+    }
+  }
+
+  async run() {
+    clearTerminal();
+    // Display just the directory name being scanned
+    this.spinner.log(
+      `📂 Scanning repository: ${path.basename(process.cwd())}`,
+      "\x1b[34m",
+    );
+    try {
+      this.parseArguments();
+      await this.checkDependencies();
+      await this.getCurrentBranch();
+
+      // Handle count-only mode and exit early
+      if (this.countOnly) {
+        await this.countBranches();
+        return;
+      }
+
+      if (this.untrackedOnly) {
+        await this.checkUntrackedBranches();
+      } else {
+        await this.checkBranches();
+      }
+
+      this.displayResults();
+      await this.deleteBranches();
+    } catch (error) {
+      this.spinner.error(`An error occurred: ${error.message}`);
+      process.exit(1);
+    }
+  }
+}
+
+module.exports = GitCleanupTool;

package/src/utils/index.js

@@ -0,0 +1,22 @@
+const { execSync } = require("child_process");
+
+function clearTerminal() {
+  // Clear screen and scroll-back buffer on all platforms
+  if (process.platform === "win32") {
+    // Windows: Use cls command and clear scroll-back
+    try {
+      execSync("cls", { stdio: "inherit" });
+    } catch {
+      // Fallback for Windows
+      process.stdout.write("\x1B[2J\x1B[0f\x1B[3J");
+    }
+  } else {
+    // Unix-like systems (macOS, Linux): Clear screen and scroll-back
+    process.stdout.write("\x1B[2J\x1B[0f\x1B[3J");
+  }
+
+  // Additional reset for cursor position
+  process.stdout.write("\x1B[H");
+}
+
+module.exports = clearTerminal;

package/src/utils/spinner.js

@@ -0,0 +1,75 @@
+const colors = {
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+};
+
+class Spinner {
+  constructor(message = "Loading...") {
+    this.message = message;
+    this.frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    this.current = 0;
+    this.interval = null;
+    this.isSpinning = false;
+  }
+
+  start() {
+    if (this.isSpinning) return;
+    this.isSpinning = true;
+    process.stdout.write("\x1b[?25l"); // Hide cursor
+    this.interval = setInterval(() => {
+      process.stdout.write(
+        `\r\x1b[K${colors.blue}${this.frames[this.current]} ${this.message}${colors.reset}`,
+      );
+      this.current = (this.current + 1) % this.frames.length;
+    }, 100);
+  }
+
+  stop() {
+    if (!this.isSpinning) return;
+    this.isSpinning = false;
+    clearInterval(this.interval);
+    this.interval = null;
+    process.stdout.write("\r\x1b[K"); // Clear line
+    process.stdout.write("\x1b[?25h"); // Show cursor
+  }
+
+  updateMessage(message) {
+    this.message = message;
+  }
+
+  success(message) {
+    this.stop();
+    console.log(`${colors.green}✅ ${message}${colors.reset}`);
+  }
+
+  error(message) {
+    this.stop();
+    console.log(`${colors.red}❌ ${message}${colors.reset}`);
+  }
+
+  warning(message) {
+    this.stop();
+    console.log(`${colors.yellow}⚠️  ${message}${colors.reset}`);
+  }
+
+  info(message) {
+    this.stop();
+    console.log(`${colors.blue}ℹ️  ${message}${colors.reset}`);
+  }
+
+  debug(message, verbose = false) {
+    if (!verbose) return;
+    this.stop();
+    console.log(`${colors.blue}🔍 DEBUG: ${message}${colors.reset}`);
+  }
+
+  log(message, color = "") {
+    console.log(`${color}${message}${colors.reset}`);
+  }
+}
+
+module.exports = Spinner;