@bragduck/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bragduck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,494 @@
+# Bragduck CLI
+
+> Transform your git commits 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)
+
+## 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.
+
+### 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
+
+## Installation
+
+```bash
+npm install -g @bragduck/cli
+```
+
+## Usage
+
+### Quick Start
+
+1. **Install globally:**
+   ```bash
+   npm install -g @bragduck/cli
+   ```
+
+2. **Initialize and authenticate:**
+   ```bash
+   bragduck init
+   ```
+   This opens your browser for OAuth authentication. Once completed, your credentials are securely stored.
+
+3. **Scan your commits:**
+   ```bash
+   cd /path/to/your/git/repo
+   bragduck scan
+   ```
+   Select commits interactively, preview AI-refined brags, and create them.
+
+4. **View your brags:**
+   ```bash
+   bragduck list
+   ```
+
+### Commands
+
+#### `bragduck init`
+
+Authenticate with Bragduck using OAuth. Opens your browser for authentication and securely stores credentials.
+
+```bash
+bragduck init
+```
+
+#### `bragduck scan`
+
+Scan git commits and create brags with AI-powered refinement.
+
+```bash
+# Scan last 30 days (default)
+bragduck scan
+
+# Scan last 60 days
+bragduck scan --days 60
+
+# Include all commits (not just yours)
+bragduck scan --all
+
+# Combine options
+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
+
+**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
+
+#### `bragduck list`
+
+List your existing brags with filtering and pagination.
+
+```bash
+# List all brags (default: 50)
+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:**
+- `-l, --limit <number>` - Number of brags to display (default: 50)
+- `-o, --offset <number>` - Number of brags to skip (default: 0)
+- `-t, --tags <tags>` - Filter by tags (comma-separated)
+- `-s, --search <query>` - Search brags by keyword
+
+#### `bragduck config`
+
+Manage CLI configuration.
+
+```bash
+# List all configuration values
+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)
+
+#### `bragduck logout`
+
+Clear stored credentials from your system.
+
+```bash
+bragduck logout
+```
+
+### Global Options
+
+Available for all commands:
+
+```bash
+# Enable debug mode (shows detailed logs)
+bragduck --debug <command>
+
+# Skip automatic version check
+bragduck --skip-version-check <command>
+
+# Show version
+bragduck --version
+
+# Show help
+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
+
+### 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
+
+### Platform Support
+- ✅ macOS (Tested)
+- ✅ Windows (Compatible)
+- ✅ Linux (Compatible)
+- ✅ Node.js ≥18.0.0
+
+## Configuration
+
+Configuration is stored in `~/.config/bragduck/config.json` (or equivalent on your OS).
+
+### Available Settings
+
+| 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 |
+
+### Credentials Storage
+
+Credentials are encrypted and stored at:
+- **File**: `~/.bragduck/credentials.enc`
+- **Encryption**: AES-256-GCM with machine-specific key derivation
+- **Access**: Only accessible by the CLI on your machine
+
+## Troubleshooting
+
+### Authentication Issues
+
+**Problem**: "Not authenticated" error when running commands
+
+**Solution**:
+```bash
+# Re-authenticate
+bragduck logout
+bragduck init
+```
+
+### Git Repository Not Found
+
+**Problem**: "Not a git repository" error
+
+**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
+```
+
+### No Commits Found
+
+**Problem**: "No commits found in the last X days"
+
+**Solution**:
+```bash
+# Increase the scan days
+bragduck scan --days 90
+
+# Or include all commits (not just yours)
+bragduck scan --all
+```
+
+### 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
+
+# Check if custom API URL is correct
+bragduck config get apiBaseUrl
+```
+
+### 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
+```
+
+### Enable Debug Mode
+
+For any issues, enable debug mode to see detailed logs:
+
+```bash
+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
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/medhatdawoud/bragduck-cli.git
+cd bragduck-cli
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+### 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
+```
+
+### 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:**
+- ✅ 122 tests passing
+- 📊 50% code coverage (focused on core logic)
+- 🧪 7 test suites covering:
+  - Services (Storage, Git, API)
+  - 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)
+│   └── 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
+```
+
+### Tech Stack
+
+**Core:**
+- TypeScript 5.x
+- Node.js ≥18.0.0
+- Commander.js (CLI framework)
+
+**Build & Test:**
+- tsup (TypeScript bundler with esbuild)
+- Vitest (testing framework)
+- ESLint + Prettier
+
+**Dependencies:**
+- @inquirer/prompts (interactive UI)
+- simple-git (Git operations)
+- ofetch (HTTP client)
+- chalk, ora, cli-table3, boxen (terminal styling)
+- conf (configuration management)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### 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`)
+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 [PLAN.md](PLAN.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**

package/dist/bin/bragduck.d.ts

@@ -0,0 +1,2 @@
+
+export {  }