# 🤖 AI Commit Toolkit

[![npm version](https://badge.fury.io/js/%40cirrusinvicta%2Fai-commit-toolkit.svg)](https://badge.fury.io/js/%40cirrusinvicta%2Fai-commit-toolkit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

One-command setup for AI-powered conventional commits with OpenAI integration, automated versioning, and seamless deployment workflows.

## ⚡ Quick Start

```bash
# Navigate to your project
cd your-project

# Install locally (recommended for customization)
npm install --save-dev @cirrusinvicta/ai-commit-toolkit

# Setup AI commit toolkit
npx ai-commit-toolkit setup

# Set your OpenAI API key
export OPENAI_API_KEY="your-api-key-here"

# Start using AI-powered commits
git add .
git commit  # AI generates your commit message automatically!
```

## 🎯 What You Get

- ✅ **Intelligent AI commit message generation** using OpenAI GPT-4o-mini with comprehensive change analysis
- ✅ **Smart file filtering** automatically excludes `node_modules/`, `package-lock.json`, and other noise
- ✅ **Multi-file change handling** generates cohesive messages for complex commits with multiple files
- ✅ **Conventional commit format enforcement** with commitlint integration
- ✅ **Consistent scope mapping system** with predefined scopes for features, technical areas, and cross-cutting concerns
- ✅ **Husky hooks integration** for seamless git workflow automation
- ✅ **Centralized configuration system** for easy customization and team consistency
- ✅ **Accurate length validation** correctly validates subject line length (not total message)
- ✅ **Semantic versioning support** with automated releases
- ✅ **Robust fallback mechanisms** when AI is unavailable
- ✅ **Comprehensive testing suite** with 35+ validation tests

## 📦 Installation

### Project-Specific Installation (Recommended)

```bash
# Navigate to your project directory
cd your-project

# Install as a dev dependency
npm install --save-dev @cirrusinvicta/ai-commit-toolkit

# Setup the toolkit in your project
npx ai-commit-toolkit setup
```

**Why Local Installation?**

- ✅ **Project-specific configuration** - Each project can have customized AI prompts and settings
- ✅ **Version consistency** - Team members use the same toolkit version
- ✅ **Better customization** - Edit `config/ai-prompts.conf` to tailor AI behavior for your project
- ✅ **No global conflicts** - Avoid version conflicts between different projects

### Global Installation (Alternative)

```bash
npm install -g @cirrusinvicta/ai-commit-toolkit
ai-commit-toolkit setup --type generic  # or ansible, vue, react
```

> **Note on Project Types**: Currently, all project types (`generic`, `ansible`, `vue`, `react`) use identical configurations and templates. The `--type` parameter is provided for future extensibility when project-specific customizations are added. For now, using any type will result in the same setup.

## � Updating

### Quick Update (Recommended)

```bash
# Update package and preserve your customizations
npm update @cirrusinvicta/ai-commit-toolkit
npx ai-commit-toolkit setup
```

✅ **Safe**: Preserves all your custom prompts and configurations  
✅ **Automatic**: Adds new features without manual intervention

### Reset to Latest (with backup)

```bash
# Reset everything to latest defaults with backup
npx ai-commit-toolkit setup --force --backup
```

⚠️ **Note**: Creates backup files, overwrites configurations

📖 **Detailed Instructions**: See [Update Workflow Guide](docs/UPDATE_WORKFLOW.md) for comprehensive update scenarios and troubleshooting.

## �🛠️ Usage

### Automated Usage (Recommended)

```bash
# Make your changes
git add .

# Commit with AI (hook automatically generates message)
git commit
# ✨ Editor opens with AI-generated conventional commit message
```

### Manual AI Generation

```bash
# Generate and commit in one step
npx ai-commit

# Interactive helper with guidance
npx ai-commit-helper

# Test your setup
npx ai-commit-test
```

## 🏷️ Scope Mapping & Consistency

The toolkit includes a comprehensive scope mapping system to ensure consistent commit messages across your team:

### Quick Scope Reference

```bash
# View all available scopes
npx ai-commit-toolkit scopes

# View specific categories
npx ai-commit-toolkit scopes --category features

# Interactive scope helper
npm run ai-commit-scopes
```

### Example Scope Usage

```bash
# Feature areas with hierarchical scopes
feat(mail.allow-block-lists): add search functionality to Allow/Block Lists page
feat(dns.policies): implement custom filtering rules
feat(reports.email-traffic): add real-time monitoring dashboard

# Cross-cutting concerns
chore(a11y): add aria labels to form inputs on settings page
feat(mobile): improve touch navigation for dashboard
perf(api): optimize database queries for better response times

# Technical improvements
fix(ui): resolve button alignment issues in mail interface
docs(api): update authentication endpoint documentation
test(auth): add integration tests for multi-factor authentication
```

### Predefined Scope Categories

- **🎯 Feature Areas**: `mail`, `dns`, `reports`, `settings`, `auth`, `billing`, `dashboard`, `admin`
- **⚙️ Technical Areas**: `api`, `ui`, `db`, `perf`, `security`, `infra`, `docs`, `tests`
- **🔄 Cross-cutting**: `a11y`, `i18n`, `mobile`, `seo`, `analytics`, `monitoring`

📖 **Detailed Guide**: See [`docs/SCOPE_MAPPING.md`](docs/SCOPE_MAPPING.md) for comprehensive scope mapping documentation.

## 🧪 Testing

```bash
# Comprehensive validation (35+ tests total)
npm test

# Individual test suites
npm run test:config      # Configuration system (23 tests)
npx ai-commit-test      # Basic validation (12 tests)

# Test with actual commit generation
npx ai-commit-test --create-test-file
```

## ⚙️ Configuration

The AI Commit Toolkit uses a centralized configuration system for easy customization.

### Project Types

The toolkit supports different project types via the `--type` parameter:

- `generic` (default) - Universal configuration suitable for any project
- `ansible` - For Ansible playbooks and roles
- `vue` - For Vue.js applications
- `react` - For React applications

**Current Status**: All project types currently use identical configurations. The framework exists for future expansion when project-specific templates and prompts are added.

## 🚀 Recent Improvements

### Enhanced AI Commit Generation

- **Comprehensive Change Analysis**: No more truncated diffs - AI now sees full context of your changes
- **Smart Multi-File Handling**: Generates cohesive messages for complex commits with many files
- **Intelligent File Filtering**: Automatically excludes noise files like `node_modules/` and `package-lock.json`
- **Accurate Length Validation**: Correctly validates only the subject line length (72 chars) instead of total message
- **Better Commit Categorization**: Improved logic for choosing appropriate conventional commit types and scopes

### Example: Before vs After

**Before** (limited context):

```
chore(husky): add commit-msg and prepare-commit-msg hooks
⚠️ Warning: Message exceeds 100 characters (false positive)
```

**After** (full context):

```
chore(setup): initialize AI commit toolkit

- Add Husky hooks for commit message validation
- Configure commitlint for conventional commits
- Create environment and configuration files
- Install project dependencies and scripts
```

### AI Prompts Configuration

After setup, all AI prompts and settings are stored in `config/ai-prompts.conf`:

```bash
# Main AI commit generation prompt
AI_COMMIT_PROMPT="Generate a conventional commit message..."

# OpenAI API Configuration
OPENAI_MODEL="gpt-4o-mini"
OPENAI_MAX_TOKENS=100
OPENAI_TEMPERATURE=0.3

# File exclusion patterns (automatically filtered from AI context)
AI_COMMIT_EXCLUDE="node_modules/ package-lock.json .env"

# Git ignore patterns (what should never be committed)
# Note: package-lock.json is NOT excluded - it should be committed for reproducible builds
GITIGNORE_EXCLUDE="node_modules .env"

# Commit message validation
MAX_COMMIT_LENGTH=100
WARN_COMMIT_LENGTH=72
```

### Customizing Prompts

To customize the AI prompts for your project:

1. **After setup**: Edit `config/ai-prompts.conf` in your project root
2. **Modify prompts**: Update `AI_COMMIT_PROMPT` to match your project's style and requirements
3. **Adjust exclusions**: Add patterns to `AI_COMMIT_EXCLUDE` to filter out files you don't want in AI context
4. **Fine-tune settings**: Change OpenAI model, token limits, or validation rules
5. **Test changes**: Run `npx ai-commit-test` to validate your configuration

**Example Customizations:**

```bash
# For a React project
AI_COMMIT_EXCLUDE="node_modules/ package-lock.json .env build/ dist/"

# For more detailed messages
OPENAI_MAX_TOKENS=150
OPENAI_TEMPERATURE=0.4

# For stricter length limits
MAX_COMMIT_LENGTH=72
WARN_COMMIT_LENGTH=60
```

### 🛡️ Configuration Protection & Updates

The AI Commit Toolkit automatically protects your custom configurations during package updates:

#### **Safe Updates (Default)**

```bash
# Update the package
npm update @cirrusinvicta/ai-commit-toolkit

# Run setup - preserves your customizations
npx ai-commit-toolkit setup
```

**What happens:**

- ✅ Your custom prompts and settings are preserved
- ✅ New configuration options are automatically added
- ✅ Scripts are updated to the latest version
- ✅ No user intervention required

#### **Force Update with Backup**

```bash
# Reset to defaults with backup
npx ai-commit-toolkit setup --force --backup
```

**What happens:**

- 📋 Creates timestamped backup files (`.backup.timestamp`)
- 🔄 Overwrites all configurations with latest templates
- 💾 Allows manual recovery from backups if needed

#### **Available Options**

| Option               | Description                             |
| -------------------- | --------------------------------------- |
| `--force`            | Overwrite existing configuration files  |
| `--backup`           | Create backups before overwriting       |
| `--no-skip-existing` | Process all files (don't skip existing) |

#### **Update Workflow Example**

```bash
# Step 1: Update package
npm update @cirrusinvicta/ai-commit-toolkit

# Step 2: Safe update (preserves customizations)
npx ai-commit-toolkit setup

# If you want to reset everything:
npx ai-commit-toolkit setup --force --backup

# Check what changed
git diff config/ai-prompts.conf
```

For detailed update workflows and troubleshooting, see [`docs/UPDATE_WORKFLOW.md`](docs/UPDATE_WORKFLOW.md).

### Environment Variables

Required:

- `OPENAI_API_KEY`: Your OpenAI API key

Optional:

- `OPENAI_MODEL`: Override the default model (default: gpt-4o-mini)
- `OPENAI_MAX_TOKENS`: Override token limit (default: 100)

## 🆘 Support

- 📖 [Documentation](docs/)
- 🤝 [Contributing Guide](CONTRIBUTING.md)
- 🐛 [Issue Tracker](https://github.com/CirrusInvicta/ai-commit-toolkit/issues)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:

- Development setup and workflow
- Coding standards and best practices
- Testing requirements and procedures
- Release process and versioning
- How to submit bug reports and feature requests

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Made with ❤️ by Cirrus Invicta**

Transform your commit workflow with intelligent AI that understands your full codebase context and generates meaningful, accurate commit messages for even the most complex changes.