@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 - ✅ **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.