Merge pull request #6 from gagip/feature/cli-generate

feat: add generate subcommand to CLI

Author: gagip

README.md

@@ -23,6 +23,7 @@ git-log-analysis/
 │   │   ├── file_processor.py        # File processing
 │   │   └── encoding_handler.py      # Encoding handling
 │   ├── cli/                         # CLI subcommands
+│   │   ├── generate_command.py      # generate subcommand
 │   │   ├── parse_command.py         # parse subcommand
 │   │   ├── search_command.py        # search subcommand
 │   │   └── projects_command.py      # projects subcommand
@@ -33,25 +34,16 @@ git-log-analysis/
 └── data/                            # Data to analyze
 ```
 
-## Installation & Requirements
-
-### Requirements
+## Requirements
 
 - Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
 - Git must be installed on the system
 
-### Package Installation
-
-**Using UV (recommended)**:
+## Installation
 
 ```bash
-uv pip install mcp pytest
-```
-
-**Using pip**:
-
-```bash
-pip install mcp pytest
+uv sync
 ```
 
 ## Usage
@@ -61,37 +53,41 @@ pip install mcp pytest
 Extracts logs from a Git repository on a monthly basis:
 
 ```bash
-python git_log_analysis/git_monthly_log_generator.py <repo_path> <start_year> <start_month>
+uv run cli.py generate -r <repo_path> -y <start_year> [-m <start_month>]
 ```
 
 **Example:**
 
 ```bash
-python git_log_analysis/git_monthly_log_generator.py <repository absolute directory path> 2021 8
+# Generate from January 2021 (default month)
+uv run cli.py generate -r /path/to/repo -y 2021
+
+# Generate from August 2021
+uv run cli.py generate -r /path/to/repo -y 2021 -m 8
 ```
 
-This command generates monthly Git logs from August 2021 to the present in the `<repository absolute directory path>/git_logs_by_month/` directory.
+This command generates monthly Git logs from the specified month (default: January) to the present in the `<repo_path>/git_logs_by_month/` directory.
 
 ### 2. Analyze Git Logs (CLI)
 
 Parse generated Git log files and save results as JSON:
 
 ```bash
-python cli.py parse -l <log_directory> -o <output_directory>
+uv run cli.py parse -l <log_directory> -o <output_directory>
 ```
 
 **Example:**
 
 ```bash
-python cli.py parse -l data/project_git_logs_by_month -o results/project
+uv run cli.py parse -l data/project_git_logs_by_month -o results/project
 ```
 
 ### 3. Search Commits (CLI)
 
 Search parsed commits:
 
 ```bash
-python cli.py search -r <results_directory> -k <keyword>
+uv run cli.py search -r <results_directory> -k <keyword>
 ```
 
 **Options:**
@@ -111,7 +107,7 @@ python cli.py search -r <results_directory> -k <keyword>
 View available projects and commit counts:
 
 ```bash
-python cli.py projects -r <results_directory>
+uv run cli.py projects -r <results_directory>
 ```
 
 ### 5. Integrate with Claude Desktop via MCP Server
@@ -160,8 +156,5 @@ Configure the Claude Desktop config file for your OS:
 ## Tests
 
 ```bash
-# Run tests
 uv run pytest
-# or
-python -m pytest
 ```

cli.py

@@ -7,6 +7,7 @@
 import sys
 import io
 from git_log_analysis.cli import (
+    setup_generate_parser,
     setup_parse_parser,
     setup_search_parser,
     setup_projects_parser,
@@ -24,14 +25,16 @@ def main():
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Subcommands:
+  generate   Extract monthly Git logs from a repository
   parse      Convert Git log files to JSON
   search     Search commits from parsed JSON
   projects   View project list and statistics
 
 For detailed usage of each subcommand:
-  python cli.py parse --help
-  python cli.py search --help
-  python cli.py projects --help
+  uv run cli.py generate --help
+  uv run cli.py parse --help
+  uv run cli.py search --help
+  uv run cli.py projects --help
         """,
     )
 
@@ -44,6 +47,7 @@ def main():
     )
 
     # Setup each subcommand
+    setup_generate_parser(subparsers)
     setup_parse_parser(subparsers)
     setup_search_parser(subparsers)
     setup_projects_parser(subparsers)

docs/architecture.md

@@ -34,7 +34,17 @@ List Projects: View all managed projects along with their total commit counts.
 
 Get Commit Changes: Retrieve detailed diffs and modification statistics for a specific commit hash.
 
-## 5. Core Module Architecture
+## 5. MCP Server Constraints
+
+The MCP server runs in **stdio mode** — stdout is reserved exclusively for MCP protocol communication. Violating this causes the server to hang silently with no response to the client.
+
+**Rules for any code called from MCP tool handlers:**
+
+- Never use `print()` — use `logging` instead (logs go to a file, not stdout)
+- Never write to `sys.stdout` directly
+- Subprocess calls must not inherit stdout (use `subprocess.PIPE` or redirect to a file)
+
+## 6. Core Module Architecture
 
 Parser: Interprets Git log formats and transforms them into data objects.
 

docs/usage.md

@@ -3,28 +3,20 @@
 ## Setup
 
 ```bash
-# Install dependencies using uv (recommended)
-uv sync --dev
-
-# Or using pip
-pip install mcp pytest ruff
+uv sync
 ```
 
 ## Testing
 
 ```bash
-# Configure tests first
-cp tests/config.py.example tests/config.py
-# Edit tests/config.py to set RESULTS_DIR
-
 # Run all tests
 uv run pytest
 
 # Run specific test file
-pytest tests/test_query_engine.py
+uv run pytest tests/test_query_engine.py
 
 # Run with verbose output
-pytest -v
+uv run pytest -v
 ```
 
 ## Linting
@@ -39,55 +31,61 @@ uv run ruff check --fix .
 
 ## CLI Usage
 
-The CLI supports three subcommands: `parse`, `search`, and `projects`.
+The CLI supports four subcommands: `generate`, `parse`, `search`, and `projects`.
 
 **1. Generate monthly Git logs:**
 
 ```bash
-python git_log_analysis/git_monthly_log_generator.py <repo_path> <start_year> <start_month>
+uv run cli.py generate -r <repo_path> -y <start_year> [-m <start_month>]
+
+# Generate from January 2024 (default month)
+uv run cli.py generate -r /path/to/repo -y 2024
+
+# Generate from June 2024
+uv run cli.py generate -r /path/to/repo -y 2024 -m 6
 ```
 
 **2. Parse logs to JSON:**
 
 ```bash
-python cli.py parse -l <log_dir> -o <output_dir>
+uv run cli.py parse -l <log_dir> -o <output_dir>
 
 # Example
-python cli.py parse -l data/project1_logs -o results/project1
+uv run cli.py parse -l data/project1_logs -o results/project1
 ```
 
 **3. Search commits:**
 
 ```bash
 # Basic keyword search
-python cli.py search -r results -k "fix bug"
+uv run cli.py search -r results -k "fix bug"
 
 # Date range search
-python cli.py search -r results -s 2024-01-01 -e 2024-12-31
+uv run cli.py search -r results -s 2024-01-01 -e 2024-12-31
 
 # Filter by author
-python cli.py search -r results -a "홍길동"
+uv run cli.py search -r results -a "홍길동"
 
 # Filter by project
-python cli.py search -r results -p project1 -k "feature"
+uv run cli.py search -r results -p project1 -k "feature"
 
 # Export to JSON
-python cli.py search -r results -k "update" --format json -o results.json
+uv run cli.py search -r results -k "update" --format json -o results.json
 
 # Export to CSV
-python cli.py search -r results -a "김철수" --format csv -o report.csv
+uv run cli.py search -r results -a "김철수" --format csv -o report.csv
 
 # Limit results
-python cli.py search -r results -k "refactor" --limit 10
+uv run cli.py search -r results -k "refactor" --limit 10
 
 # Combined filters
-python cli.py search -r results -k "authentication" -a "developer" -s 2024-01-01 --format json
+uv run cli.py search -r results -k "authentication" -a "developer" -s 2024-01-01 --format json
 ```
 
 **4. List projects:**
 
 ```bash
-python cli.py projects -r results
+uv run cli.py projects -r results
 
 # Example output:
 # Available projects in results:

git_log_analysis/cli/__init__.py

@@ -1,7 +1,13 @@
 """CLI commands module"""
 
+from .generate_command import setup_generate_parser
 from .parse_command import setup_parse_parser
-from .search_command import setup_search_parser
 from .projects_command import setup_projects_parser
+from .search_command import setup_search_parser
 
-__all__ = ["setup_parse_parser", "setup_search_parser", "setup_projects_parser"]
+__all__ = [
+    "setup_generate_parser",
+    "setup_parse_parser",
+    "setup_search_parser",
+    "setup_projects_parser",
+]

git_log_analysis/cli/generate_command.py

@@ -0,0 +1,73 @@
+"""Generate command: Extract monthly git logs from a repository"""
+
+import argparse
+from pathlib import Path
+
+from git_log_analysis.git_monthly_log_generator import generate_git_logs
+
+from .types import SubParser
+
+
+def setup_generate_parser(subparsers: SubParser):
+    """Setup argument parser for generate subcommand
+
+    Args:
+        subparsers: argparse subparsers object
+    """
+    parser = subparsers.add_parser(
+        "generate",
+        help="Extract monthly Git logs from a repository",
+        description="Runs 'git log' on a local repository and saves the output as monthly .txt files.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  uv run cli.py generate -r /path/to/repo -y 2024 -m 1
+  uv run cli.py generate -r /path/to/repo -y 2023 -m 6
+        """,
+    )
+
+    parser.add_argument(
+        "-r",
+        "--repo-path",
+        required=True,
+        help="Path to the local Git repository",
+    )
+    parser.add_argument(
+        "-y",
+        "--year",
+        required=True,
+        type=int,
+        help="Start year (YYYY)",
+    )
+    parser.add_argument(
+        "-m",
+        "--month",
+        type=int,
+        choices=range(1, 13),
+        default=1,
+        help="Start month (1-12, default: 1)",
+    )
+
+    parser.set_defaults(func=_generate_command)
+
+
+def _generate_command(args):
+    """Execute generate command
+
+    Args:
+        args: Parsed command line arguments
+    """
+    repo_path = Path(args.repo_path).resolve()
+    print(f"Generating Git logs from: {repo_path}")
+    print(f"   Start: {args.year}-{args.month:02d}\n")
+
+    try:
+        generate_git_logs(repo_path, args.year, args.month)
+    except (FileNotFoundError, ValueError) as e:
+        print(f"❌ Error: {e}")
+        return 1
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
+        return 1
+
+    return 0