# 🛠️ maintainer-kit

[![CI](https://github.com/leveluphamza14-cpu/maintainer-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/leveluphamza14-cpu/maintainer-kit/actions)
[![npm version](https://img.shields.io/npm/v/maintainer-kit.svg?style=flat-square)](https://www.npmjs.com/package/maintainer-kit)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Compatible-purple.svg?style=flat-square)](https://modelcontextprotocol.io/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/leveluphamza14-cpu/maintainer-kit/pulls)

> **Autonomous open-source maintainer toolkit:** Repository health audits, semantic changelog generator, PR diff reviewer, and Model Context Protocol (MCP) server.

`maintainer-kit` automates the time-consuming administrative and review workflows that open-source maintainers face every day. Built with **zero runtime dependencies**, it runs instantaneously via CLI, acts as a **GitHub Action** in your CI pipelines, and connects directly to **GitHub Copilot, ChatGPT, and Claude** as an MCP server.

---

## ✨ Features

- 🛡️ **Repository Health & Security Audit**: Audits open-source standards (`LICENSE`, `README`, `CONTRIBUTING`, `SECURITY.md`, `.gitignore`, workflows) and scans for accidentally tracked API keys or sensitive credentials.
- 📝 **Semantic Changelog Generator**: Parses commit history, groups changes by [Conventional Commits](https://www.conventionalcommits.org/), flags breaking changes, and formats release notes ready for GitHub Releases.
- 🔍 **PR Diff & Code Smell Reviewer**: Inspects git diffs for security risks (`eval`, raw SQL, leaked credentials), leftover debug statements (`console.log`, `debugger`), and computes PR risk ratings.
- 🏷️ **Intelligent Issue Triager**: Classifies incoming issues into categories (`bug`, `feature`, `docs`, `perf`), suggesting labels, priority, and next steps.
- 🤖 **Native Model Context Protocol (MCP) Server**: Exposes all maintainer tools over standard JSON-RPC stdio to AI assistants like VS Code Copilot, ChatGPT, Cursor, and Claude Desktop.
- ⚡ **Composite GitHub Action**: Easily pluggable into any repository's `.github/workflows` to run automated compliance checks on pull requests.

---

## 🚀 Quick Start

Run instantly with no installation required via `npx`:

```bash
# Audit the current repository's open-source health and compliance
npx maintainer-kit audit

# Generate release notes and changelog from commit history
npx maintainer-kit changelog

# Review uncommitted or staged changes for security smells and quality
npx maintainer-kit review --staged

# Triage an incoming issue
npx maintainer-kit triage "Uncaught exception on login" "App crashes with null pointer when token is expired"
```

Or install globally:

```bash
npm install -g maintainer-kit
```

---

## 📖 CLI Usage & Commands

### 1. Repository Audit (`audit`)
Scans the current repository against open-source community standards, missing governance files, sensitive credential leaks, and CI pipeline presence.

```bash
maintainer-kit audit
```
*Options:*
- `--json`: Output report as machine-readable JSON.

```
📋 OPEN-SOURCE REPOSITORY HEALTH AUDIT  100/100 PASS

Repository Path: /path/to/my-project

  ✔ PASS Open Source License
    Found standard file: LICENSE
  ✔ PASS README Documentation
    Found standard file: README.md
  ✔ PASS Contributing Guidelines
    Found standard file: CONTRIBUTING.md
  ✔ PASS Security Vulnerability Policy
    Found standard file: SECURITY.md
  ✔ PASS GitHub Actions CI Workflows
    Found 1 automated workflow file(s): ci.yml
  ✔ PASS Tracked Secrets & Credential Leak Scan
    No exposed secrets or API credentials detected in repository files.

Summary: 8 Passed, 0 Warnings, 0 Failures
```

---

### 2. Semantic Changelog (`changelog`)
Automatically aggregates commits into semantic groups: Features 🚀, Bug Fixes 🐛, Performance ⚡, Refactoring ♻️, Documentation 📚, and Breaking Changes ⚠️.

```bash
# Generate changelog from latest git tag to HEAD
maintainer-kit changelog

# Generate changelog from a specific release tag
maintainer-kit changelog --tag v1.0.0
```

---

### 3. PR Diff Reviewer (`review`)
Scans staged changes or compares against a base branch:

```bash
# Review staged git changes
maintainer-kit review --staged

# Review against main branch
maintainer-kit review --base main
```

---

### 4. Issue Triage (`triage`)
Classifies issue title and body to suggest categorization and labels:

```bash
maintainer-kit triage "Crash when clicking save" "App crashes with TypeError in store.js"
```

---

## 🤖 Model Context Protocol (MCP) Setup

`maintainer-kit` implements the open [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) standard. You can plug it into **Claude Desktop**, **VS Code Copilot**, **Cursor**, or **ChatGPT**.

### Claude Desktop Configuration
Add the server to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "maintainer-kit": {
      "command": "npx",
      "args": ["-y", "maintainer-kit", "mcp"]
    }
  }
}
```

### Available MCP Tools:
- `maintainer_audit`: Audit repository open-source compliance and file standards.
- `maintainer_changelog`: Generate release notes from git commit history.
- `maintainer_review_diff`: Review a git diff for vulnerabilities and code smells.
- `maintainer_triage_issue`: Triage and categorize an incoming issue.

---

## ⚡ Use as a GitHub Action

Add `maintainer-kit` to your continuous integration pipeline to audit every pull request:

Create `.github/workflows/maintainer.yml`:

```yaml
name: Maintainer Audit

on:
  pull_request:
    branches: [main]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: leveluphamza14-cpu/maintainer-kit@v1
        with:
          command: 'audit'
```

---

## 💻 Programmatic Library API

You can also use `maintainer-kit` as a typed Node.js module:

```typescript
import { runAudit, reviewDiff, generateChangelog, triageIssue } from "maintainer-kit";

// Run compliance audit
const audit = runAudit("./my-repo");
console.log(`Health Score: ${audit.score}/100`);

// Inspect a git diff
const review = reviewDiff({ staged: true });
console.log(`Risk Level: ${review.summary.riskLevel}`);

// Generate release notes
const changelog = generateChangelog({ version: "v1.1.0" });
console.log(changelog.markdown);
```

---

## 🤝 Contributing

Contributions are very welcome! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on setup, testing, and coding standards.

1. Fork this repository
2. Create your feature branch (`git checkout -b feat/awesome-feature`)
3. Commit your changes following [Conventional Commits](https://www.conventionalcommits.org/)
4. Push to the branch (`git push origin feat/awesome-feature`)
5. Open a Pull Request

---

## 🛡️ License

This project is licensed under the [MIT License](LICENSE) © 2026 Hamza Adil.