marsdevs-git-workreport/README.md

🚀 Advanced Git Work Report Generator with AI-Powered Summaries - Generate intelligent daily work reports from Git commit history using Claude AI or OpenRouter. Perfect for DevOps teams, development companies, and client reporting with comprehensive stati

# MarsDevs Git Work Report

🚀 **Advanced Git Work Report Generator with AI-Powered Summaries** - Generate intelligent daily work reports from Git commit history using Claude AI or OpenRouter. Perfect for DevOps teams, development companies, and client reporting with comprehensive statistics and multiple output formats.

## Features

- 🤖 **AI-Powered Summaries**: Generate intelligent summaries using Anthropic's Claude AI or OpenRouter (free tier available)
- 📅 **Date-based reporting**: Generate reports for any specific date
- 📊 **Comprehensive statistics**: Track commits, total lines changed, and authors
- 🎨 **Multiple formats**: Output in text, JSON, or Markdown formats
- ⚡ **Fast and efficient**: Built with TypeScript and optimized for performance
- 🌍 **Timezone support**: Handle different timezones for accurate reporting

## Installation

```bash
npm install -g marsdevs-git-workreport
```

## Quick Start

### Basic Usage

Generate a work report for today:
```bash
marsdevs-git-workreport
```

Generate a work report for a specific date:
```bash
marsdevs-git-workreport 11/08/2025
```

### AI-Powered Summaries

#### Using Anthropic (Claude AI)
Generate a report with AI-generated summary using Anthropic API:
```bash
marsdevs-git-workreport 11/08/2025 --anthropic-key YOUR_API_KEY
```

#### Using OpenRouter (Free Tier Available)
Generate a report with AI-generated summary using OpenRouter API:
```bash
marsdevs-git-workreport 11/08/2025 --openrouter-key YOUR_API_KEY
```

#### Specify AI Provider (Optional)
You can explicitly specify which AI provider to use (auto-detected by default):
```bash
marsdevs-git-workreport 11/08/2025 --ai-provider openrouter --openrouter-key YOUR_API_KEY
marsdevs-git-workreport 11/08/2025 --ai-provider anthropic --anthropic-key YOUR_API_KEY
```

**Note**: The AI provider is automatically detected based on which API key you provide. You only need to specify `--ai-provider` if you want to override the auto-detection.

### Advanced Usage

Generate a report in JSON format:
```bash
marsdevs-git-workreport 11/08/2025 --format json
```

Save report to a file:
```bash
marsdevs-git-workreport 11/08/2025 --output reports/work-report.txt
```

Generate Markdown report with AI summary:
```bash
marsdevs-git-workreport 11/08/2025 --format markdown --output report.md --openrouter-key YOUR_API_KEY
```

## Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `[date]` | Date in DD/MM/YYYY format | Today |
| `-f, --format <format>` | Output format: text, json, or markdown | text |
| `-o, --output <file>` | Output file path | Console output |
| `--no-stats` | Exclude statistics from the report | false |
| `--no-files` | Exclude file lists from the report | false |
| `--timezone <tz>` | Timezone for date parsing | local |
| `--repo <path>` | Path to Git repository | Current directory |
| `--anthropic-key <key>` | Anthropic API key for AI-generated summaries | None |
| `--openrouter-key <key>` | OpenRouter API key for AI-generated summaries (free tier available) | None |
| `--ai-provider <provider>` | AI provider to use: anthropic or openrouter (auto-detected) | Auto-detected |

## AI Providers

### Anthropic (Claude AI)
- **API Key**: Get from [Anthropic Console](https://console.anthropic.com/)
- **Models**: Claude-3-Haiku, Claude-3-Sonnet, Claude-3-Opus
- **Cost**: Pay-per-use pricing

### OpenRouter
- **API Key**: Get from [OpenRouter](https://openrouter.ai/) (free tier available)
- **Models**: Access to multiple AI models including Claude, GPT, and others
- **Cost**: Free tier with generous limits, then pay-per-use

## Examples

### Example 1: Daily Work Report with Anthropic AI Summary
```bash
marsdevs-git-workreport 15/08/2025 --anthropic-key YOUR_API_KEY
```

### Example 2: Daily Work Report with OpenRouter AI Summary
```bash
marsdevs-git-workreport 15/08/2025 --openrouter-key YOUR_API_KEY
```

### Example 3: Specify OpenRouter Provider Explicitly
```bash
marsdevs-git-workreport 15/08/2025 --ai-provider openrouter --openrouter-key YOUR_API_KEY
```

**Output:**
```
================================================================================
GIT WORK REPORT - 15/08/2025
================================================================================

SUMMARY:
  Date: 15/08/2025
  Total Commits: 8
  Total Lines Changed: 312
  Authors: John Doe, Jane Smith

AI-GENERATED SUMMARY:
  • Implemented user authentication system with login/logout functionality
• Added responsive design improvements to the UI
• Fixed several UI bugs across the application
• Added comprehensive test coverage for authentication features

STATISTICS:
  Insertions: 245 lines
  Deletions: 67 lines
  Net Changes: 178 lines
  Average Commits per Author: 4.00

================================================================================
Report generated on 8/15/2025, 5:30:45 PM
AI Provider: openrouter
```

### Example 4: JSON Report
```bash
marsdevs-git-workreport 15/08/2025 --format json --output report.json
```

**Output:**
```json
{
  "date": "15/08/2025",
  "totalCommits": 8,
  "totalInsertions": 245,
  "totalDeletions": 67,
  "authors": ["John Doe", "Jane Smith"],
  "aiSummary": "• Implemented user authentication system with login/logout functionality\n• Added responsive design improvements to the UI\n• Fixed several UI bugs across the application\n• Added comprehensive test coverage for authentication features",
  "totalLinesChanged": 312
}
```

## AI Summary Features

The AI-powered summary feature uses Anthropic's Claude AI or OpenRouter to analyze commit messages and generate intelligent summaries of daily work. The AI:

- **Analyzes commit messages** to understand what work was accomplished
- **Provides context** about the types of changes made
- **Generates bullet-point summaries** that are easy to scan and understand
- **Focuses only on actual changes** without extra words or explanations
- **Falls back gracefully** to basic summaries when AI is not available
- **Saves API costs** by not making AI calls when no commits are found

**Summary Format**: AI summaries are generated as concise bullet points that list only the actual changes made, without any introductory or closing sentences. This makes them easy to read and understand at a glance.

**Cost Optimization**: The tool automatically detects when no commits exist for a date and displays "No commits detected for this date." without making any AI API calls, helping you save on API costs.

To use AI summaries, you'll need an Anthropic API key or OpenRouter API key. Get them at:
- Anthropic: [https://console.anthropic.com/](https://console.anthropic.com/)
- OpenRouter: [https://openrouter.ai/](https://openrouter.ai/) (free tier available)

## Use Cases

### For Development Companies
- **Client Reporting**: Generate intelligent daily/weekly work summaries for clients
- **Progress Tracking**: Monitor team productivity with AI-generated insights
- **Project Validation**: Verify work completed on specific dates with clear summaries
- **Time Tracking**: Support time tracking systems with intelligent commit analysis

### For DevOps Teams
- **Deployment Validation**: Verify what code was deployed with AI summaries
- **Release Notes**: Generate intelligent release notes from commit history
- **Audit Trails**: Create audit reports with clear work descriptions
- **Performance Monitoring**: Track code changes with contextual summaries

## Programmatic Usage

You can also use the package programmatically:

```typescript
import { GitAnalyzer, ReportGenerator } from 'marsdevs-git-workreport';

async function generateReport() {
  const analyzer = new GitAnalyzer();
  const generator = new ReportGenerator();
  
  const report = await analyzer.generateWorkReport('15/08/2025', {
    anthropicApiKey: 'YOUR_API_KEY'
  });
  const formattedReport = generator.generateReport(report, { format: 'markdown' });
  
  console.log(formattedReport);
}
```

## Requirements

- Node.js >= 16.0.0
- Git repository (local or remote)
- Git command line tools
- Anthropic API key (optional, for AI summaries)

## Troubleshooting

### Common Issues

1. **"not a git repository" error**
   - Make sure you're in a Git repository directory
   - Use `--repo <path>` to specify repository location

2. **"Invalid date format" error**
   - Use DD/MM/YYYY format (e.g., 15/08/2025)
   - Alternative formats: YYYY-MM-DD, MM/DD/YYYY

3. **No commits found**
   - Verify the date has commits
   - Check timezone settings with `--timezone` option

4. **AI summary not working**
   - Ensure you have a valid Anthropic API key
   - Check your internet connection
   - The tool will fall back to basic summaries if AI is unavailable

### Getting Help

```bash
marsdevs-git-workreport --help
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details