@bragduck/cli 2.29.2 → 2.30.2

package/README.md

@@ -1,6 +1,8 @@
 # Bragduck CLI
 
-> Transform your GitHub Pull Requests into polished achievements with AI-powered refinement
+> Part of the [BragDuck monorepo](../../README.md). Run all commands from the monorepo root unless noted otherwise.
+
+> Sync work items from GitHub, GitLab, Bitbucket, Jira, and Confluence 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)
@@ -9,22 +11,22 @@
 
 ## Overview
 
-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.
+Bragduck CLI helps developers track and showcase their achievements by syncing work items from multiple sources (GitHub, GitLab, Bitbucket, Jira, Confluence) and refining them into polished "brags" using AI. Perfect for performance reviews, portfolio updates, or keeping track of accomplishments.
 
 ### Why Bragduck?
 
-- 🤖 **AI-Powered**: Automatically refines your commit messages into professional achievements
-- 🎯 **Context-Aware**: Analyzes commit diffs, file changes, and patterns
-- 🔒 **Secure**: OAuth authentication with encrypted credential storage
-- 🎨 **Beautiful UI**: Interactive terminal experience with colors and spinners
-- 🚀 **Fast**: Optimized build size (69KB) for quick installation and execution
-- 🌐 **Cross-Platform**: Works on macOS, Windows, and Linux
+- **Multi-Source Sync**: Pull work items from GitHub, GitLab, Bitbucket, Jira, and Confluence
+- **AI-Powered**: Automatically refines work items into professional achievements
+- **Context-Aware**: Analyzes PRs, issues, and project data for meaningful brags
+- **Secure**: OAuth and token-based authentication with encrypted credential storage
+- **Beautiful UI**: Interactive terminal experience with colors and spinners
+- **Cross-Platform**: Works on macOS, Windows, and Linux
 
 ## Prerequisites
 
 Before installing Bragduck CLI, you need:
 
-1. **Node.js ≥18.0.0**
+1. **Node.js >=18.0.0**
    ```bash
    node --version  # Should be v18.0.0 or higher
    ```
@@ -49,40 +51,56 @@ Before installing Bragduck CLI, you need:
 
 ## Installation
 
+### As a global tool (end users)
+
 ```bash
 npm install -g @bragduck/cli
 ```
 
+### For development (monorepo)
+
+From the monorepo root:
+
+```bash
+pnpm install
+pnpm --filter @bragduck/cli build
+```
+
 ## Usage
 
 ### Quick Start
 
-1. **Install GitHub CLI and authenticate:**
+1. **Install Bragduck CLI globally:**
    ```bash
-   # Install GitHub CLI (if not already installed)
-   brew install gh  # macOS
-
-   # Authenticate with GitHub
-   gh auth login
+   npm install -g @bragduck/cli
    ```
 
-2. **Install Bragduck CLI globally:**
+2. **Authenticate with Bragduck:**
    ```bash
-   npm install -g @bragduck/cli
+   bragduck auth login
    ```
+   This opens your browser for OAuth authentication. Once completed, your credentials are securely stored.
 
-3. **Initialize and authenticate:**
+3. **Connect your services** (optional, for GitHub/GitLab/Bitbucket/Jira/Confluence):
    ```bash
-   bragduck init
+   # GitHub: install and authenticate with GitHub CLI
+   brew install gh && gh auth login
+
+   # GitLab: authenticate with personal access token
+   bragduck auth gitlab
+
+   # Bitbucket: authenticate with API token
+   bragduck auth bitbucket
+
+   # Atlassian (Jira + Confluence): authenticate via OAuth
+   bragduck auth atlassian
    ```
-   This opens your browser for OAuth authentication. Once completed, your credentials are securely stored.
 
-4. **Scan your merged PRs:**
+4. **Sync your work items:**
    ```bash
-   cd /path/to/your/github/repo
-   bragduck scan
+   bragduck sync
    ```
-   Select PRs interactively, preview AI-refined brags, and create them.
+   Select services, review AI-refined brags, and create them.
 
 5. **View your brags:**
    ```bash
@@ -91,56 +109,64 @@ npm install -g @bragduck/cli
 
 ### Commands
 
-#### `bragduck init`
+#### `bragduck auth [subcommand]`
 
-Authenticate with Bragduck using OAuth. Opens your browser for authentication and securely stores credentials.
+Manage authentication for Bragduck and connected services.
 
 ```bash
-bragduck init
+# Login to Bragduck (default)
+bragduck auth login
+
+# Check authentication status for all services
+bragduck auth status
+
+# Authenticate with GitLab
+bragduck auth gitlab
+
+# Authenticate with Bitbucket
+bragduck auth bitbucket
+
+# Authenticate with Atlassian (Jira + Confluence)
+bragduck auth atlassian
 ```
 
-#### `bragduck scan`
+**Subcommands:**
+- `login` - Authenticate with Bragduck (default if no subcommand)
+- `status` - Show authentication status for all services
+- `bitbucket` - Authenticate with Bitbucket using API token
+- `gitlab` - Authenticate with GitLab using personal access token
+- `atlassian` - Authenticate with Atlassian Cloud via OAuth 2.0
+
+#### `bragduck sync`
 
-Scan merged GitHub Pull Requests and create brags with AI-powered refinement.
+Sync work items from authenticated services and create brags with AI-powered refinement.
 
 ```bash
-# Scan last 30 days (default, your PRs only)
-bragduck scan
+# Interactive sync (choose services and items)
+bragduck sync
+
+# Sync last 7 days
+bragduck sync --days 7
+
+# Sync last 24 hours
+bragduck sync --today
 
-# Scan last 60 days
-bragduck scan --days 60
+# Sync all services, skip prompts, auto-accept
+bragduck sync --turbo
 
-# Include all PRs (not just yours)
-bragduck scan --all
+# Sync all authenticated services
+bragduck sync --all
 
-# Combine options
-bragduck scan --days 90 --all
+# Sync a specific source
+bragduck sync --source github
 ```
 
 **Options:**
-- `-d, --days <number>` - Number of days to scan (default: 30)
-- `-a, --all` - Include all PRs, not just current user's
-
-**Workflow:**
-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`)
+- `-d, --days <number>` - Number of days to scan
+- `-t, --today` - Scan the last 24 hours (shorthand for --days 1)
+- `--turbo` - Skip all prompts, auto-select all items, auto-accept refinements
+- `-a, --all` - Sync all authenticated services (skip service selection)
+- `-s, --source <type>` - Explicit source type (github)
 
 #### `bragduck list`
 
@@ -153,17 +179,11 @@ bragduck list
 # Show 25 brags
 bragduck list --limit 25
 
-# Show next page (skip first 50)
-bragduck list --offset 50
-
 # Filter by tags
 bragduck list --tags "feature,bugfix"
 
 # Search by keyword
 bragduck list --search "implemented authentication"
-
-# Combine filters
-bragduck list --tags "feature" --search "API" --limit 20
 ```
 
 **Options:**
@@ -223,28 +243,27 @@ bragduck --help
 ## Features
 
 ### Core Features
-- 🔐 **OAuth Authentication** - Secure authentication with local callback server
-- 🤖 **AI-Powered Refinement** - Transforms commit messages into professional achievements
-- ✅ **Interactive Selection** - Checkbox interface for selecting commits
-- 📊 **Rich Preview** - Table preview of refined brags before creation
-- 🔍 **Smart Filtering** - Filter brags by tags and search keywords
-- 📄 **Pagination Support** - Handle large numbers of brags efficiently
+- **Multi-Source Sync** - GitHub, GitLab, Bitbucket, Jira, Confluence
+- **OAuth & Token Auth** - Secure authentication per service
+- **AI-Powered Refinement** - Transforms work items into professional achievements
+- **Interactive Selection** - Checkbox interface for selecting items
+- **Rich Preview** - Table preview of refined brags before creation
+- **Smart Filtering** - Filter brags by tags and search keywords
+- **Turbo Mode** - Fully automated sync with no prompts
 
 ### Technical Features
-- 🔒 **Secure Storage** - Encrypted credential storage with AES-256-GCM
-- 🎨 **Beautiful UI** - Colorful terminal output with spinners and tables
-- 🔄 **Auto-Updates** - Automatic version checking with update notifications
-- 🐛 **Debug Mode** - Detailed logging for troubleshooting
-- ⚙️ **Configurable** - Customize API URL, scan days, and more
-- 🚀 **Lightweight** - Only 69KB build size
-- ✨ **TypeScript** - Fully typed for better IDE support
+- **Secure Storage** - Encrypted credential storage with AES-256-GCM
+- **Beautiful UI** - Colorful terminal output with spinners and tables
+- **Auto-Updates** - Automatic version checking with update notifications
+- **Debug Mode** - Detailed logging for troubleshooting
+- **Configurable** - Customize API URL, scan days, and more
+- **TypeScript** - Fully typed for better IDE support
 
 ### Platform Support
-- ✅ macOS (Tested)
-- ✅ Windows (Compatible)
-- ✅ Linux (Compatible)
-- ✅ Node.js ≥18.0.0
-- ✅ GitHub repositories only (GitLab/Bitbucket not supported)
+- macOS (Tested)
+- Windows (Compatible)
+- Linux (Compatible)
+- Node.js >=18.0.0
 
 ## Configuration
 
@@ -276,19 +295,15 @@ Credentials are encrypted and stored at:
 ```bash
 # Re-authenticate
 bragduck logout
-bragduck init
+bragduck auth login
 ```
 
-### Git Repository Not Found
-
-**Problem**: "Not a git repository" error
+**Problem**: Service not showing in sync
 
 **Solution**:
 ```bash
-# Make sure you're in a git repository
-cd /path/to/your/git/repo
-git status  # Verify it's a git repo
-bragduck scan
+# Check which services are authenticated
+bragduck auth status
 ```
 
 ### GitHub CLI Not Authenticated
@@ -304,73 +319,17 @@ gh auth login
 gh auth status
 ```
 
-### Not a GitHub Repository
+### No Work Items Found
 
-**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"
+**Problem**: "No items found in the last X days"
 
 **Solution**:
 ```bash
 # Increase the scan days
-bragduck scan --days 90
-
-# 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
+bragduck sync --days 90
 
-# Windows
-winget install --id GitHub.cli
-
-# Linux - see https://github.com/cli/cli#installation
-
-# Verify installation
-gh --version
-```
-
-### API Connection Issues
-
-**Problem**: Network or API errors
-
-**Solution**:
-```bash
-# Check your internet connection
-# Try with debug mode to see detailed logs
-bragduck --debug scan
-```
-
-### Version Check Failures
-
-**Problem**: Version check taking too long or failing
-
-**Solution**:
-```bash
-# Skip version check for this run
-bragduck --skip-version-check scan
-
-# Or disable it permanently
-bragduck config set autoVersionCheck false
+# Sync all authenticated services
+bragduck sync --all
 ```
 
 ### Enable Debug Mode
@@ -381,136 +340,54 @@ For any issues, enable debug mode to see detailed logs:
 bragduck --debug <command>
 ```
 
-This shows:
-- API requests and responses
-- Authentication status
-- Configuration reads/writes
-- Internal operations
-
 ## Development
 
 ### Prerequisites
 
-- Node.js ≥ 18.0.0
-- npm or yarn
+- Node.js >= 18.0.0
+- pnpm (workspace package manager)
 
-### Setup
+### Setup (monorepo)
 
 ```bash
-# Clone the repository
-git clone https://github.com/medhatdawoud/bragduck-cli.git
-cd bragduck-cli
-
-# Install dependencies
-npm install
+# From the monorepo root
+pnpm install
 
-# Build the project
-npm run build
+# Build the CLI
+pnpm --filter @bragduck/cli build
 
 # Run tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Lint code
-npm run lint
-
-# Format code
-npm run format
+pnpm --filter @bragduck/cli test
 ```
 
 ### Project Structure
 
 ```
-bragduck-cli/
-├── src/
-│   ├── commands/      # CLI commands
-│   ├── services/      # Business logic services
-│   ├── ui/            # Terminal UI components
-│   ├── types/         # TypeScript type definitions
-│   ├── utils/         # Utility functions
-│   └── cli.ts         # CLI entry point
-├── tests/             # Test files
-├── dist/              # Built files
-└── package.json
+src/
+├── commands/      # CLI commands
+├── services/      # Business logic services
+├── ui/            # Terminal UI components
+├── types/         # TypeScript type definitions
+├── utils/         # Utility functions
+└── cli.ts         # CLI entry point
 ```
 
 ### Scripts
 
 | Script | Description |
 |--------|-------------|
-| `npm run build` | Build the project with tsup |
-| `npm run dev` | Build in watch mode for development |
-| `npm test` | Run test suite (122 tests) |
-| `npm run test:coverage` | Run tests with coverage report |
-| `npm run test:ui` | Run tests with interactive UI |
-| `npm run lint` | Lint code with ESLint |
-| `npm run lint:fix` | Lint and auto-fix issues |
-| `npm run format` | Format code with Prettier |
-| `npm run typecheck` | Type check without building |
-
-### Testing
-
-The project has comprehensive test coverage:
-
-```bash
-# Run all tests
-npm test
-
-# Run with coverage report
-npm run test:coverage
-
-# Run specific test file
-npx vitest run tests/commands/config.test.ts
-
-# Run in watch mode
-npx vitest
-```
-
-**Test Stats:**
-- ✅ 126 tests passing
-- 📊 50% code coverage (focused on core logic)
-- 🧪 8 test suites covering:
-  - Services (Storage, Git, API, GitHub)
-  - Commands (Config, List)
-  - Utilities (Version, Errors)
-
-### Architecture
-
-```
-src/
-├── commands/       # CLI command implementations
-│   ├── init.ts     # OAuth authentication flow
-│   ├── scan.ts     # Main feature - commit scanning
-│   ├── list.ts     # List brags with filtering
-│   ├── config.ts   # Configuration management
-│   └── logout.ts   # Credential cleanup
-├── services/       # Business logic services
-│   ├── 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)
-│   ├── formatters.ts   # Output formatting (chalk, cli-table3)
-│   └── spinners.ts     # Loading indicators (ora)
-├── utils/          # Utility functions
-│   ├── errors.ts       # Custom error classes
-│   ├── logger.ts       # Logging utility
-│   ├── version.ts      # Version checking & comparison
-│   ├── validators.ts   # Input validation
-│   ├── browser.ts      # Cross-platform browser opening
-│   └── oauth-server.ts # Local OAuth callback server
-└── types/          # TypeScript type definitions
-```
+| `pnpm --filter @bragduck/cli build` | Build the project with tsup |
+| `pnpm --filter @bragduck/cli dev` | Build in watch mode for development |
+| `pnpm --filter @bragduck/cli test` | Run test suite |
+| `pnpm --filter @bragduck/cli test:coverage` | Run tests with coverage report |
+| `pnpm --filter @bragduck/cli lint` | Lint code with ESLint |
+| `pnpm --filter @bragduck/cli lint:fix` | Lint and auto-fix issues |
 
 ### Tech Stack
 
 **Core:**
 - TypeScript 5.x
-- Node.js ≥18.0.0
+- Node.js >=18.0.0
 - Commander.js (CLI framework)
 
 **Build & Test:**
@@ -530,61 +407,22 @@ src/
 
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome.
 
 ### Quick Contribution Guide
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
 3. Make your changes
-4. Run tests (`npm test`)
-5. Commit your changes (`git commit -m 'Add amazing feature'`)
-6. Push to the branch (`git push origin feature/amazing-feature`)
+4. Run tests (`pnpm --filter @bragduck/cli test`)
+5. Commit your changes
+6. Push to the branch
 7. Open a Pull Request
 
-### Development Guidelines
-
-- Write tests for new features
-- Follow existing code style (ESLint + Prettier)
-- Update documentation for user-facing changes
-- Keep commits atomic and well-described
-
-## Support
-
-### Getting Help
-
-- 📖 **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)
-
-### Reporting Issues
-
-When reporting issues, please include:
-
-1. **Environment**: OS, Node.js version, npm version
-2. **Steps to reproduce**: Clear steps to reproduce the issue
-3. **Expected behavior**: What you expected to happen
-4. **Actual behavior**: What actually happened
-5. **Debug output**: Run with `--debug` flag and include output
-
-Example:
-```bash
-bragduck --debug scan
-```
-
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details
 
-## Acknowledgments
-
-Built with ❤️ using:
-- [Commander.js](https://github.com/tj/commander.js) - CLI framework
-- [Inquirer.js](https://github.com/SBoudrias/Inquirer.js) - Interactive prompts
-- [simple-git](https://github.com/steveukx/git-js) - Git operations
-- [Vitest](https://vitest.dev) - Testing framework
-- And many other great open-source projects
-
 ---
 
 **Made by [Medhat Dawoud](https://github.com/medhatdawoud)** | **Powered by AI**