GitLab MR CLI

A command-line tool that extracts comments from GitLab Merge Requests and generates structured todo files that can be used by LLMs to address code review feedback.

Features

• Extract comments from GitLab Merge Requests
• Generate structured todo files with MR-level and line-level comments
• Secure token storage in user's home directory
• Support for both resolved and unresolved comments
• LLM-friendly output format

Installation

From npm (Recommended)

# Install globally
npm install -g @erp-ai/gitlab-mr-cli

# Or install locally in your project
npm install @erp-ai/gitlab-mr-cli

From Source

1. Clone or download this repository
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. (Optional) Link globally:

   npm link

Usage

Basic Usage

# Run with MR URL as argument
gitlab-mr "https://gitlab.com/your-project/-/merge_requests/123"

# Or run without URL and enter it interactively
gitlab-mr

Options

# Specify output file
gitlab-mr -o my-todo.md "https://gitlab.com/your-project/-/merge_requests/123"

# Provide token directly (not recommended for security)
gitlab-mr -t your-token "https://gitlab.com/your-project/-/merge_requests/123"

Configuration Management

# Manage stored tokens and configuration
gitlab-mr config

Setup Steps

1. Install dependencies:

   npm install

2. Build the project:

   npm run build

3. Create GitLab Personal Access Token:

   • Go to GitLab → Profile → Personal Access Tokens
   • Create token with scopes: api, read_api, read_repository
   • Copy the token (you'll need it when running the CLI)

4. Run the CLI:

   npm start

   Or if linked globally:

   gitlab-mr

5. First run:

   • Enter your GitLab MR URL when prompted
   • Enter your personal access token when prompted
   • Token will be securely stored in ~/.gitlab-mr-cli/config.json

Generated Todo File Format

The tool generates markdown files with the following structure:

# MR Todo: Your MR Title

**MR URL:** https://gitlab.com/project/-/merge_requests/123
**Source Branch:** feature-branch
**Target Branch:** main
**Created:** 2024-01-01

## Description
MR description here...

## Comments and Todo Items
Total comments: 5
Unresolved comments: 3

### MR-Level Comments
Comments that apply to the entire MR...

### Line-Level Comments
#### File: src/example.ts
##### Line 42 - Comment 1 ❌
**Author:** reviewer
**Date:** 2024-01-01

Comment text here...

## Instructions for LLM
This section provides context for LLMs on how to process the todo items.

Development Scripts

# Development mode with auto-reload
npm run dev

# Build TypeScript
npm run build

# Type checking
npm run typecheck

# Linting
npm run lint

# Start built version
npm start

# Testing
npm test              # Run all tests
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run test:ci       # Run tests for CI (with coverage, no watch)

Testing

The project includes comprehensive unit tests with coverage reporting:

• Test Framework: Jest with TypeScript support
• Coverage Target: 80% minimum for branches, functions, lines, and statements
• Test Files: Located in tests/ directory
• Coverage Reports: Generated in coverage/ directory (HTML, LCOV, JSON)

Running Tests

# Run all tests once
npm test

# Run tests in watch mode (development)
npm run test:watch

# Generate coverage report
npm run test:coverage

# View coverage report
open coverage/lcov-report/index.html

Test Structure

tests/
├── fixtures/           # Test data and mocks
├── __mocks__/         # Module mocks
├── setup.ts           # Test setup configuration
├── gitlab-client.test.ts
├── config.test.ts
└── todo-generator.test.ts

File Structure

src/
├── index.ts          # Main CLI application
├── gitlab-client.ts  # GitLab API client
├── config.ts         # Configuration management
├── todo-generator.ts # Todo file generation
└── types.ts          # TypeScript type definitions

Security Notes

• Personal access tokens are stored in ~/.gitlab-mr-cli/config.json
• File permissions are set to be readable only by the user
• Never commit tokens to version control
• Use environment variables for CI/CD if needed

Troubleshooting

Common Issues

1. Invalid MR URL: Ensure the URL follows the format: https://gitlab.com/project/-/merge_requests/123
2. Authentication failed: Check your personal access token has the required scopes
3. Network issues: Verify you can access the GitLab instance
4. Permission errors: Ensure you have read access to the project

Getting Help

gitlab-mr --help
gitlab-mr config --help

Publishing to npm

Prerequisites

1. npm Account: Create account at npmjs.com
2. Organization Access: Ensure you have access to @erp-ai organization
3. Authentication: Login to npm CLI

npm login

Publishing Steps

1. Prepare for Release:

   # Ensure all tests pass
   npm test
      
   # Run linting
   npm run lint
      
   # Type check
   npm run typecheck
      
   # Build the project
   npm run build

2. Version Management:

   # Patch version (1.0.0 → 1.0.1)
   npm version patch
      
   # Minor version (1.0.0 → 1.1.0)
   npm version minor
      
   # Major version (1.0.0 → 2.0.0)
   npm version major

3. Publish to npm:

   # Publish to npm registry
   npm publish
      
   # Or publish with specific tag
   npm publish --tag beta

Automated Publishing

The project includes automated quality checks:

• prepublishOnly: Runs tests, linting, and type checking before publishing
• preversion: Validates code before version bump
• postversion: Pushes git tags after version bump

Package Information

• Package Name: @erp-ai/gitlab-mr-cli
• Organization: @erp-ai
• Registry: npmjs.com
• Access: Public package

Version History

Check the npm registry for version history and download statistics.

License

MIT