git-coco 0.22.11 → 0.23.1

package/README.md

@@ -10,361 +10,112 @@
 [![Last Commit](https://img.shields.io/github/last-commit/gfargo/coco)](https://github.com/gfargo/coco/tree/main)
 [![Discord](https://img.shields.io/discord/1176716060825767948)](https://discord.gg/KGu9nE9Ejx)
 
-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 with **first-class Conventional Commits support**, creates changelogs, summarizes code changes, performs code reviews, and more - with new features being added regularly!
+An AI-powered git assistant that generates meaningful commit messages, creates changelogs, and streamlines your development workflow.
 
 **✨ Key Features:**
 
 - 🤖 **AI-Powered Commit Messages** - Generate contextual commits from your staged changes
-- 📋 **Conventional Commits** - Full support with automatic validation and formatting
+- 📋 **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)
+- 📦 **Package Manager Friendly** - Works with npm, yarn, and pnpm
+- 👥 **Team Ready** - Shared configurations and enterprise deployment
 
-## Commands
-
-- **`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.
-
-- **`recap`**: summarize changes from working-tree, or yesterday, or in the last month, or since the last tag.
-
-- **`review`**: perform a code review on the changes in the working directory.
-
-- **`init`**: step by step wizard to set up `coco` globally or for a project.
-
-- **`help`**: display help for `coco` commands.
-
-## Getting Started
-
-**`coco init`** is the first step to getting started with `coco`. It will guide you through the installation process, including setting up your OpenAI API key and configuring `coco` to your preferences.
-
-```bash
-# For local project use
-npx git-coco@latest init -l project
-
-# For global use
-npx git-coco@latest init -l global
-```
-
-## Usage
-
-### **`coco commit`**
-
-Generates commit messages based on staged changes with intelligent commitlint integration.
-
-```bash
-coco
-
-# or 
-
-coco commit
-```
-
-#### Conventional Commits & Commitlint Integration
-
-`coco` provides first-class support for Conventional Commits with intelligent commitlint integration:
-
-**Conventional Commits Support:**
-
-- **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
-
-#### Command Options
-
-**Basic Options:**
+## Quick Start
 
 ```bash
-# Interactive mode - opens editor for review and editing
-coco -i, --interactive
+# Try without installing
+npx git-coco@latest init
 
-# Verbose output - shows detailed processing information
-coco --verbose
-
-# Help - display command help
-coco --help
-```
+# Install globally  
+npm install -g git-coco
 
-**Commit Enhancement Options:**
-
-```bash
-# Add content to the end of the generated commit message
-coco --append "Resolves #128"
-
-# Automatically append Jira/Linear ticket ID from branch name
-coco -t, --append-ticket
-
-# Add extra context to guide commit generation
-coco -a, --additional "Resolves UX bug with sign up button"
-
-# 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
+# Setup and configure
+coco init
 
-# Open commit message in editor before proceeding
-coco --open-in-editor
+# Generate your first commit
+git add .
+coco -i
 ```
 
-### **`coco changelog`**
-
-Creates changelogs from commit history.
-
-```bash
-# Basic changelog for current branch
-coco changelog
+## Commands
 
-# Interactive mode
-coco changelog -i, --interactive
-```
+- **`coco commit`** - Generate commit messages from staged changes
+- **`coco changelog`** - Create changelogs from commit history  
+- **`coco recap`** - Summarize recent changes and activity
+- **`coco review`** - AI-powered code review of your changes
+- **`coco init`** - Interactive setup wizard
 
-#### Changelog Options
+## Usage Examples
 
-**Range Selection:**
+### Basic Workflow
 
 ```bash
-# Specific commit range (HEAD references)
-coco changelog -r HEAD~5:HEAD
-
-# Specific commit range (commit hashes)  
-coco changelog -r abc1234:def5678
+# Make your changes
+git add .
 
-# Compare against target branch
-coco changelog -b main, --branch main
+# Generate commit message (interactive mode recommended)
+coco -i
 
-# All commits since last tag
-coco changelog -t, --since-last-tag
+# Or use stdout mode
+git commit -m "$(coco)"
 ```
 
-**Content Options:**
+### Conventional Commits
 
 ```bash
-# Include diff for each commit in analysis
-coco changelog --with-diff
-
-# Generate changelog based only on branch diff
-coco changelog --only-diff
+# Enable conventional commits format
+coco --conventional
 
-# Include author attribution
-coco changelog --author
+# With additional context
+coco -a "Fixes login timeout" --conventional
 
-# Add extra context to guide generation
-coco changelog -a "Focus on user-facing changes" --additional "Focus on user-facing changes"
+# Include ticket from branch name
+coco --append-ticket --conventional
 ```
 
-### **`coco recap`**
-
-Summarize changes across different time periods.
+### Team Workflows
 
 ```bash
-# Summarize current working directory changes
-coco recap
-
-# Interactive mode
-coco recap -i, --interactive
-```
-
-#### Recap Time Periods
+# Generate changelog for releases
+coco changelog --since-last-tag
 
-```bash
-# Yesterday's changes
+# Summarize recent work
 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
+# Code review before committing
 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
-
-`coco` offers two modes of operation: **stdout** and **interactive**, defaulting to **stdout**. You can specify your preferred mode in your config file or via command line flags.
-
-```bash
-# Stdout mode
-git commit -m $(coco)
-
-# Interactive mode
-coco -i
-```
-
-### Generate and commit all in one
-
-`coco` can generate and commit your changes in one command.
-
-```bash
-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
 
-`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:**
+Configure `coco` for your workflow with the interactive setup wizard:
 
 ```bash
-# Interactive setup wizard
+# Setup wizard
 coco init
 
-# Project-specific configuration
+# Project-specific setup
 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 (API key required)
+- **Anthropic** - Claude 3.5 Sonnet (API key required)  
+- **Ollama** - Local models, no API costs, full privacy
 
-- **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
+**Example Configuration:**
+```json
 {
-  "ignoredFiles": ["package-lock.json", "dist/*"],
-  "ignoredExtensions": [".map", ".min.js"]
+  "mode": "interactive",
+  "conventionalCommits": true,
+  "service": {
+    "provider": "openai",
+    "model": "gpt-4o"
+  }
 }
 ```
 
-**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:
@@ -372,17 +123,15 @@ For comprehensive guides, advanced usage, and detailed configuration options, vi
 ### 📚 **[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
+- **[Command Reference](https://github.com/gfargo/coco/wiki/Command-Reference)** - Detailed command options and examples
 - **[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:**
-
+- **[Using Ollama](https://github.com/gfargo/coco/wiki/Using-Ollama)** - Local AI setup for privacy and cost control
 - **[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
 
 ### 🆘 **Need Help?**
 

package/dist/index.esm.mjs

@@ -47,7 +47,7 @@ import { pathToFileURL } from 'url';
 /**
  * Current build version from package.json
  */
-const BUILD_VERSION = "0.22.11";
+const BUILD_VERSION = "0.23.1";
 
 const isInteractive = (config) => {
     return config?.mode === 'interactive' || !!config?.interactive;
@@ -11557,6 +11557,10 @@ const handler$3 = async (argv, logger) => {
         },
         factory,
         parser,
+        reviewParser: (result) => {
+            // Ensure the result is properly formatted as a string for display
+            return typeof result === 'string' ? result : String(result);
+        },
         agent: async (context, options) => {
             // Select the appropriate schema based on whether conventional commits are enabled
             const schema = USE_CONVENTIONAL_COMMITS
@@ -11684,11 +11688,15 @@ IMPORTANT RULES:
                 });
                 // Construct the full commit message using the utility function
                 const ticketId = extractTicketIdFromBranchName(branchName);
+                // Debug: Log what commitMsg looks like before formatting
+                logger.verbose(`commitMsg before formatting: ${JSON.stringify(commitMsg)}`, { color: 'blue' });
                 const fullMessage = formatCommitMessage(commitMsg, {
                     append: argv.append,
                     ticketId: ticketId || undefined,
                     appendTicket: argv.appendTicket,
                 });
+                // Debug: Log what fullMessage looks like after formatting
+                logger.verbose(`fullMessage after formatting: ${typeof fullMessage === 'string' ? fullMessage : JSON.stringify(fullMessage)}`, { color: 'blue' });
                 // If commitlint validation is needed and not skipped, validate the message
                 if ((USE_CONVENTIONAL_COMMITS || hasCommitLintConfig) && !shouldSkipCommitlintValidation) {
                     const { validateCommitMessage, CommitlintValidationError } = await Promise.resolve().then(function () { return commitlintValidator; });

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.11";
+const BUILD_VERSION = "0.23.1";
 
 const isInteractive = (config) => {
     return config?.mode === 'interactive' || !!config?.interactive;
@@ -11579,6 +11579,10 @@ const handler$3 = async (argv, logger) => {
         },
         factory,
         parser,
+        reviewParser: (result) => {
+            // Ensure the result is properly formatted as a string for display
+            return typeof result === 'string' ? result : String(result);
+        },
         agent: async (context, options) => {
             // Select the appropriate schema based on whether conventional commits are enabled
             const schema = USE_CONVENTIONAL_COMMITS
@@ -11706,11 +11710,15 @@ IMPORTANT RULES:
                 });
                 // Construct the full commit message using the utility function
                 const ticketId = extractTicketIdFromBranchName(branchName);
+                // Debug: Log what commitMsg looks like before formatting
+                logger.verbose(`commitMsg before formatting: ${JSON.stringify(commitMsg)}`, { color: 'blue' });
                 const fullMessage = formatCommitMessage(commitMsg, {
                     append: argv.append,
                     ticketId: ticketId || undefined,
                     appendTicket: argv.appendTicket,
                 });
+                // Debug: Log what fullMessage looks like after formatting
+                logger.verbose(`fullMessage after formatting: ${typeof fullMessage === 'string' ? fullMessage : JSON.stringify(fullMessage)}`, { color: 'blue' });
                 // If commitlint validation is needed and not skipped, validate the message
                 if ((USE_CONVENTIONAL_COMMITS || hasCommitLintConfig) && !shouldSkipCommitlintValidation) {
                     const { validateCommitMessage, CommitlintValidationError } = await Promise.resolve().then(function () { return commitlintValidator; });

package/package.json

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