🤖 AI Commit Toolkit

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

⚡ Quick Start

# 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)

# 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)

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)

# 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)

# 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 for comprehensive update scenarios and troubleshooting.

�🛠️ Usage

Automated Usage (Recommended)

# 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

# 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

# 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

# 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 for comprehensive scope mapping documentation.

🧪 Testing

# 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:

# 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:

# 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)

# 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

# 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

# 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.

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
• 🤝 Contributing Guide
• 🐛 Issue Tracker

🤝 Contributing

We welcome contributions! Please see our Contributing Guide 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 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.