@cirrusinvicta/ai-commit-toolkit

# 🤖 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 - ✅ **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 `configs/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. ## 🛠️ 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 ``` ## 🧪 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 `configs/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 `configs/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 ``` ### 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) ## 📄 License MIT License - see [LICENSE](LICENSE) file for details. ## 🆘 Support - 📖 [Documentation](docs/) - 🐛 [Issue Tracker](https://github.com/CirrusInvicta/ai-commit-toolkit/issues) --- **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.