git-coco 0.22.10 → 0.22.11

package/README.md

@@ -12,11 +12,20 @@
 
 Spawned by the dream to automate away the tedium of writing commit messages, `coco` has grown into a multi-facetted git assistant to expedite any developer git workflow.
 
-Currently `coco` generates commit messages, creates changelogs, summarizes code changes, perform code review, and more - with new features being added regularly!
+Currently `coco` generates commit messages with **first-class Conventional Commits support**, creates changelogs, summarizes code changes, performs code reviews, and more - with new features being added regularly!
+
+**✨ Key Features:**
+
+- 🤖 **AI-Powered Commit Messages** - Generate contextual commits from your staged changes
+- 📋 **Conventional Commits** - Full support with automatic validation and formatting
+- 🔧 **Commitlint Integration** - Seamless integration with your existing commitlint configuration
+- 📦 **Package Manager Friendly** - Works with npm, yarn, and pnpm (with automatic compatibility handling)
+- 🛠️ **Robust Error Recovery** - Advanced JSON parsing with automatic repair capabilities
+- 🏠 **Local AI Support** - Run completely offline with Ollama (no API costs, full privacy)
 
 ## Commands
 
-- **`commit`**: generates commit messages based on staged changes.
+- **`commit`**: generates commit messages based on staged changes with intelligent conventional commits support and robust error handling.
 
 - **`changelog`**: create changelogs for the current branch or a range of commits.
 
@@ -54,67 +63,190 @@ coco
 coco commit
 ```
 
-#### Commitlint Integration
+#### Conventional Commits & Commitlint Integration
+
+`coco` provides first-class support for Conventional Commits with intelligent commitlint integration:
+
+**Conventional Commits Support:**
 
-`coco` automatically detects and integrates with your project's commitlint configuration:
+- **Automatic Detection**: Enables conventional commits mode when commitlint config is detected
+- **Smart Formatting**: Generates properly formatted conventional commits (feat, fix, docs, etc.)
+- **Breaking Changes**: Supports breaking change syntax (`feat!:` and `feat(scope)!:`)
+- **Scoped Commits**: Intelligent scope detection and formatting
+- **Robust Parsing**: Advanced JSON parsing with automatic error recovery
+
+**Commitlint Integration:**
 
 - **Smart Detection**: Automatically finds commitlint config files (`.commitlintrc.*`, `commitlint.config.*`, or `package.json` with commitlint field)
 - **AI-Aware Rules**: Passes your commitlint rules to the AI for better compliance from the start
 - **Automatic Retry**: When validation fails, `coco` automatically retries generation with error feedback (up to 2 attempts)
+- **Package Manager Compatibility**: Works seamlessly with npm, yarn, and pnpm (with automatic fallback for ES module issues)
 - **User-Friendly Flow**: After auto-retries, offers options to try 2 more times or edit manually
 - **Full Validation**: Both AI-generated and manually edited commit messages are validated against your rules
 
-#### Useful options
+#### Command Options
+
+**Basic Options:**
 
 ```bash
-# --append
-# Add content to the end of the generated commit
+# Interactive mode - opens editor for review and editing
+coco -i, --interactive
+
+# Verbose output - shows detailed processing information
+coco --verbose
+
+# Help - display command help
+coco --help
+```
+
+**Commit Enhancement Options:**
+
+```bash
+# Add content to the end of the generated commit message
 coco --append "Resolves #128"
 
-# --append-ticket
-# Automatically append Jira/Linear ticket ID from the branch name to the commit message 
-coco --append-ticket
+# Automatically append Jira/Linear ticket ID from branch name
+coco -t, --append-ticket
 
-# --additional
-# Add extra context before generating the commit
-coco --additional "Resolves UX bug with sign up button"
+# Add extra context to guide commit generation
+coco -a, --additional "Resolves UX bug with sign up button"
 
-# --conventional
-# Force conventional commits mode (also enabled automatically with commitlint config)
-coco --conventional
+# Include previous commits for context (specify number)
+coco -p, --with-previous-commits 3
+```
+
+**Conventional Commits Options:**
+
+```bash
+# Force conventional commits mode
+coco -c, --conventional
+
+# Include/exclude branch name in context (default: true)
+coco --include-branch-name
+coco --no-include-branch-name
+```
+
+**Processing Options:**
+
+```bash
+# Ignore specific files (can be used multiple times)
+coco --ignored-files "*.lock" --ignored-files "dist/*"
+
+# Ignore file extensions (can be used multiple times)  
+coco --ignored-extensions ".map" --ignored-extensions ".min.js"
+
+# Use basic git status instead of full diff (faster for large changes)
+coco --no-diff
+
+# Open commit message in editor before proceeding
+coco --open-in-editor
 ```
 
 ### **`coco changelog`**
 
-Creates changelogs.
+Creates changelogs from commit history.
 
 ```bash
-# For the current branch
+# Basic changelog for current branch
 coco changelog
 
-# For a specific range (using HEAD references)
+# Interactive mode
+coco changelog -i, --interactive
+```
+
+#### Changelog Options
+
+**Range Selection:**
+
+```bash
+# Specific commit range (HEAD references)
 coco changelog -r HEAD~5:HEAD
 
-# For a specific range (using commit hashes)
+# Specific commit range (commit hashes)  
 coco changelog -r abc1234:def5678
 
-# For a target branch
-coco changelog -b other-branch
+# Compare against target branch
+coco changelog -b main, --branch main
 
-# For all commits since the last tag
-coco changelog -t
+# All commits since last tag
+coco changelog -t, --since-last-tag
+```
+
+**Content Options:**
+
+```bash
+# Include diff for each commit in analysis
+coco changelog --with-diff
+
+# Generate changelog based only on branch diff
+coco changelog --only-diff
+
+# Include author attribution
+coco changelog --author
+
+# Add extra context to guide generation
+coco changelog -a "Focus on user-facing changes" --additional "Focus on user-facing changes"
 ```
 
 ### **`coco recap`**
 
-Summarize the working-tree, or other configured ranges
+Summarize changes across different time periods.
 
 ```bash
-# Summarize all working directory changes
+# Summarize current working directory changes
 coco recap
 
-# Or these available ranges
-coco recap --yesterday | --last-week | --last-month | --last-tag
+# Interactive mode
+coco recap -i, --interactive
+```
+
+#### Recap Time Periods
+
+```bash
+# Yesterday's changes
+coco recap --yesterday
+
+# Last week's changes  
+coco recap --last-week, --week
+
+# Last month's changes
+coco recap --last-month, --month
+
+# Changes since last git tag
+coco recap --last-tag, --tag
+
+# Current branch changes
+coco recap --current-branch
+```
+
+### **`coco review`**
+
+Perform AI-powered code review on your changes.
+
+```bash
+# Review current working directory changes
+coco review
+
+# Interactive mode
+coco review -i, --interactive
+
+# Review specific branch
+coco review -b feature-branch, --branch feature-branch
+```
+
+### **`coco init`**
+
+Interactive setup wizard for configuring coco.
+
+```bash
+# Setup wizard (will prompt for scope)
+coco init
+
+# Configure for current project only
+coco init --scope project
+
+# Configure globally for current user
+coco init --scope global
 ```
 
 ### Stdout vs. Interactive Mode
@@ -137,13 +269,126 @@ coco -i
 coco -s
 ```
 
+### **Conventional Commits Examples**
+
+`coco` excels at generating properly formatted conventional commits:
+
+```bash
+# Basic conventional commit
+coco --conventional
+# Output: feat: add user authentication system
+
+# With scope
+coco --conventional -a 'fixes login timeout'
+# Output: fix(auth): resolve login timeout issue
+
+# With additional context and ticket
+coco --conventional --additional "Resolves login issues" --append-ticket
+# Output: feat(auth): add OAuth2 integration
+#         
+#         Implement OAuth2 flow with Google and GitHub providers.
+#         Resolves login issues
+#         
+#         Part of **PROJ-123**
+```
+
 ## Configuration
 
-The `.coco.config` documentation has moved to our [wiki](https://github.com/gfargo/coco/wiki/Config-Overview). Here, you'll find detailed information on setting up and customizing your experience.
+`coco` offers flexible configuration through multiple methods with a clear priority system. See the complete [Configuration Overview](CONFIG_OVERVIEW.md) for detailed setup instructions, all available options, and examples.
+
+**Quick Start:**
+
+```bash
+# Interactive setup wizard
+coco init
+
+# Project-specific configuration
+coco init --scope project
+
+# Global user configuration  
+coco init --scope global
+```
+
+**Configuration Methods (in priority order):**
+
+1. Command line flags (highest priority)
+2. Environment variables
+3. Project config (`.coco.config.json`)
+4. Git config (`.gitconfig`)
+5. XDG config directory (lowest priority)
+
+**AI Providers:**
+
+- **OpenAI**: GPT-4o, GPT-4o-mini, GPT-4 Turbo (API key required)
+- **Anthropic**: Claude 3.5 Sonnet, Claude 3 Haiku (API key required)  
+- **Ollama**: Local models, no API costs, full privacy - [Setup Guide](USING_OLLAMA.md)
+
+### **Ignoring Files & Extensions**
+
+`coco` can ignore specific files and extensions to focus on meaningful changes. See the complete [Ignoring Files & Extensions Guide](IGNORING_FILES_EXTENSIONS.md) for detailed configuration options and examples.
+
+**Quick Examples:**
+
+```bash
+# Command line flags
+coco --ignored-files "*.lock" --ignored-extensions ".map"
+
+# Config file
+{
+  "ignoredFiles": ["package-lock.json", "dist/*"],
+  "ignoredExtensions": [".map", ".min.js"]
+}
+```
+
+**Default Ignores:**
+
+- Files: `package-lock.json` + contents of `.gitignore`
+- Extensions: `.map`, `.lock`
+
+## Troubleshooting
+
+### **pnpm Compatibility**
+
+If you encounter ES module errors with pnpm and commitlint:
+
+```bash
+# Update commitlint packages to latest versions
+pnpm add -D @commitlint/config-conventional@latest @commitlint/cli@latest
+
+# Or continue without commitlint validation
+# coco will automatically fall back to built-in conventional commit rules
+```
+
+### **Conventional Commits Issues**
+
+- **JSON Parsing Errors**: `coco` automatically repairs common JSON formatting issues from AI responses
+- **Commitlint Validation**: If validation fails, `coco` provides clear error messages and retry options
+- **Missing Dependencies**: `coco` gracefully handles missing commitlint packages with helpful installation guidance
+
+## Documentation
+
+For comprehensive guides, advanced usage, and detailed configuration options, visit our complete documentation:
+
+### 📚 **[Coco Wiki](https://github.com/gfargo/coco/wiki)**
+
+**Essential Guides:**
+
+- **[Getting Started](https://github.com/gfargo/coco/wiki/Getting-Started)** - Complete beginner's guide from installation to first commit
+- **[Configuration Overview](https://github.com/gfargo/coco/wiki/Config-Overview)** - All configuration options and setup methods
+- **[Team Collaboration](https://github.com/gfargo/coco/wiki/Team-Collaboration)** - Enterprise deployment and team adoption strategies
+- **[Using Ollama](https://github.com/gfargo/coco/wiki/Using-Ollama)** - Local AI setup for privacy and cost control
+
+**Advanced Resources:**
+
+- **[Advanced Usage](https://github.com/gfargo/coco/wiki/Advanced-Usage)** - Custom prompts, automation, and power-user features
+- **[Troubleshooting](https://github.com/gfargo/coco/wiki/Troubleshooting)** - Solutions for common issues and debugging
+- **[Ignoring Files & Extensions](https://github.com/gfargo/coco/wiki/Ignoring-Files-&-Extensions)** - Advanced file filtering and pattern matching
 
-### **Ignoring Files**
+### 🆘 **Need Help?**
 
-You can specify files to be ignored when generating commit messages by adding them to your config file or via command line flags.  Read more about ignoring files & extensions in the [wiki](https://github.com/gfargo/coco/wiki/Ignoring-Files-&-Extensions).
+- **[Troubleshooting Guide](https://github.com/gfargo/coco/wiki/Troubleshooting)** - Comprehensive problem-solving resource
+- **[GitHub Issues](https://github.com/gfargo/coco/issues)** - Bug reports and feature requests
+- **[Discord Community](https://discord.gg/KGu9nE9Ejx)** - Real-time help and discussion
 
 ## Contribution
 

package/dist/index.esm.mjs

@@ -47,7 +47,7 @@ import { pathToFileURL } from 'url';
 /**
  * Current build version from package.json
  */
-const BUILD_VERSION = "0.22.10";
+const BUILD_VERSION = "0.22.11";
 
 const isInteractive = (config) => {
     return config?.mode === 'interactive' || !!config?.interactive;

package/dist/index.js

@@ -69,7 +69,7 @@ var readline__namespace = /*#__PURE__*/_interopNamespaceDefault(readline);
 /**
  * Current build version from package.json
  */
-const BUILD_VERSION = "0.22.10";
+const BUILD_VERSION = "0.22.11";
 
 const isInteractive = (config) => {
     return config?.mode === 'interactive' || !!config?.interactive;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-coco",
-  "version": "0.22.10",
+  "version": "0.22.11",
   "description": "zero-effort git commits with coco.",
   "author": "gfargo <ghfargo@gmail.com>",
   "license": "MIT",