gitpadi 2.0.7 → 2.1.1

package/README.md

@@ -1,102 +1,630 @@
-# 🤖 GitPadi
+# GitPadi
 
-GitPadi is a GitHub management CLI and Action built to automate the repetitive parts of maintaining open-source projects. 
+> AI-powered GitHub & GitLab automation — from your terminal or straight into CI.
 
-Whether you're a maintainer managing hundreds of issues or a contributor making your first PR, GitPadi turns multi-step GitHub workflows into single commands.
+[![npm version](https://img.shields.io/npm/v/gitpadi?color=e2ff6f&label=npm)](https://www.npmjs.com/package/gitpadi)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/Netwalls/contributor-agent?style=social)](https://github.com/Netwalls/contributor-agent)
+
+Built by [Netwalls](https://github.com/Netwalls).
 
 ---
 
-## 🚀 For Contributors
+## What is GitPadi?
+
+GitPadi is a CLI and GitHub Actions suite that automates the full lifecycle of open-source collaboration. Contributors can fork, submit PRs, fix CI failures, and reply to review comments without leaving the terminal. Maintainers can review PRs, score contributors, send escalating reminders, and auto-merge — all in one tool. Organizations and schools can create assignments, auto-grade student submissions across 5 criteria, and publish cohort leaderboards.
+
+---
 
-Stop worrying about forking, upstream remotes, and branch naming. GitPadi handles the plumbing so you can focus on the code.
+## Quick Start
 
-### Start a new contribution
 ```bash
-npx gitpadi start <issue-url>
+npx gitpadi
 ```
-This single command:
-1. **Forks** the repository to your account.
-2. **Clones** it to your machine.
-3. Sets up the **upstream remote**.
-4. Creates a **fresh feature branch** linked to the issue.
 
-### Submit your work
+Or add it to any repo in three steps:
+
+1. Copy the [drop-in workflow](#drop-in-github-actions) to `.github/workflows/gitpadi.yml`
+2. Push to your repo
+3. Every PR is now auto-reviewed, scored, and merged if it passes
+
+---
+
+## Installation
+
 ```bash
-npx gitpadi submit
+# Global install (recommended)
+npm install -g gitpadi
+
+# or with other package managers
+yarn global add gitpadi
+pnpm add -g gitpadi
+
+# or run without installing
+npx gitpadi
 ```
-When you're done, this command:
-1. **Stages** all your changes.
-2. Creates a **commit** with a clean message.
-3. **Pushes** to your fork.
-4. Opens a **Pull Request** on the original repo, auto-linked to the issue.
 
 ---
 
-## 🛠️ For Maintainers
+## GitHub Authentication
+
+On first launch, GitPadi asks for a **GitHub Personal Access Token**.
+
+1. Go to [https://github.com/settings/tokens](https://github.com/settings/tokens)
+2. Generate a new token (classic) with these scopes:
+   - `repo` — full control of private repos
+   - `read:org` — read org membership (optional, for org repos)
+3. Paste the token when prompted
 
-Manage your community and project health directly from your terminal.
+GitPadi stores your token locally at `~/.gitpadi/config.json`. It never leaves your machine.
+
+You can also set the token via environment variable:
 
-### 📋 Bulk Issue Creation
-Create dozens of issues in seconds from a simple Markdown or JSON file.
 ```bash
-npx gitpadi issues bulk -f roadmap.md
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
 ```
-*(Supports `## Heading` titles and `**Labels:**` tags).*
 
-### 🏆 Smart Contributor Scoring
-Auto-score applicants based on their GitHub history, account age, and relevance to the issue.
+---
+
+## GitLab Authentication
+
+GitPadi supports GitLab with full CLI and 5 Duo External AI agents.
+
+1. Run `npx gitpadi`
+2. Select **GitLab** from the platform selector
+3. Enter your GitLab host (e.g. `https://gitlab.com`)
+4. Paste your `glpat-xxxxxxxxxxxx` Personal Access Token
+
+GitPadi stores the GitLab token alongside your GitHub token in `~/.gitpadi/config.json`.
+
+---
+
+## Getting Started
+
 ```bash
-npx gitpadi contributors score octocat
+npx gitpadi
 ```
-Or let GitPadi find the best applicant for an issue:
-```bash
-npx gitpadi issues assign-best 42
+
+You'll see the boot sequence, then a mode selector:
+
+```
+⟨ GITPADI MODE SELECTOR ⟩
+
+? Choose your path:
+  👤  Contributor Mode     — fork, clone, sync, submit PRs
+  🛠️  Maintainer Mode      — manage issues, PRs, contributors
+  🏫  Organization/School  — assignments, grading, leaderboard
+  👋  Exit
 ```
 
-### 🔀 Advanced PR Management
-- **Review PRs**: Get an automated review (size analysis, security checks, test coverage).
-- **Fast Merge**: Squash and merge PRs directly from the CLI.
-- **CI Status**: View GitHub Action logs for a PR without opening a browser.
+Pick a mode and go. Type `q` at any text prompt to go back to the previous menu.
 
 ---
 
-## ⚡ Quick Start
+## Three CLI Modes
 
-No installation required. Just set your token and go:
+### Contributor Mode
+
+For people contributing to repositories they don't own.
+
+#### Start Contribution
+
+Fork a repo, clone it locally, set up the upstream remote, and create a branch — all in one step.
 
-```bash
-export GITHUB_TOKEN=ghp_your_token
-npx gitpadi
+```
+? Contributor Action: 🚀 Start Contribution
+? Enter Repo or Issue URL: https://github.com/org/project/issues/42
 ```
 
-### Direct Commands
-```bash
-npx gitpadi issues list --limit 100
-npx gitpadi prs review 5
-npx gitpadi release create v1.0.0
+What happens:
+1. Forks the repo to your account (skips if already forked)
+2. Asks where to clone it
+3. Clones your fork
+4. Adds the original repo as `upstream`
+5. Creates a branch named `fix/issue-42`
+
+Accepts these input formats:
+- `https://github.com/owner/repo`
+- `https://github.com/owner/repo/issues/123`
+- `owner/repo`
+
+#### Sync with Upstream
+
+```
+? Contributor Action: 🔄 Sync with Upstream
+```
+
+Fetches upstream, merges into your current branch, and warns about conflicts. Also runs automatically every time you open the Contributor menu.
+
+#### View Action Logs
+
+Shows CI/CD status of your latest commit with per-job breakdown.
+
 ```
+📋 GitHub Actions status: ❌ Failure
+
+  ✅ lint: success
+  ❌ test: failure
+     → Build failed. View details at: https://github.com/...
+```
+
+#### Submit PR
+
+Stage, commit, push, and open a pull request in one go.
+
+```
+? Contributor Action: 🚀 Submit PR
+  🔍 Detected Issue #42 from branch... Fix the login bug
+? 🚀 Ready to submit?
+  ✅ Yes, use automated metadata
+  ✍️  Edit title/message manually
+```
+
+#### Fix & Re-push
+
+When your PR's CI fails, this walks you through fixing it.
+
+```
+🔧 Fix & Re-push Workflow
+
+📋 GitHub Actions status: ❌ Failure
+
+  ✅ lint: success
+  ❌ test: failure
+```
+
+What happens:
+1. Shows which CI checks failed
+2. Waits for you to fix the code
+3. Stages everything with `git add .`
+4. Amends or creates a new commit
+5. Force-pushes with `--force-with-lease`
+6. Re-checks CI status
+
+#### Reply to Comments
+
+Read and reply to maintainer feedback on your PR without opening a browser.
+
+```
+💬 3 comment(s) on PR #15
+
+  @maintainer (src/auth.ts)
+  Can you add a test for the timeout case?
+
+? Reply to @maintainer?
+  💬  Write a reply
+  ⏩  Skip
+```
+
+Fetches both general and inline code review comments. Inline replies stay inline.
 
 ---
 
-## 🔧 Use as a GitHub Action
+### Maintainer Mode
+
+For repository owners and collaborators. GitPadi validates your permissions before entering Maintainer Mode.
+
+#### Issues
+
+| Command | What it does |
+|---------|-------------|
+| List Issues | View open/closed issues in a formatted table |
+| Create Issue | Create a new issue with title, body, and labels |
+| Create from File | Bulk-create issues from a markdown or JSON file |
+| Close Issue | Close an issue by number |
+| Reopen Issue | Reopen a closed issue |
+| Delete Issue | Permanently delete an issue (admin only) |
+| Assign | Assign a user to an issue |
+| Assign Best | Score all applicants and auto-assign the top one |
+| Search | Search issues by keyword |
+| Label | Add labels to an issue |
+
+#### Pull Requests
+
+| Command | What it does |
+|---------|-------------|
+| List PRs | View open/closed pull requests |
+| Review & Merge | Review PR + check CI + squash merge from the terminal |
+| Merge PR | Merge with squash, merge commit, or rebase |
+| Close PR | Close without merging |
+| Review | Show the full PR review table (files, size, checks) |
+| Approve | Submit an approval review |
+| Diff | Show the diff for a PR |
+
+When CI fails, GitPadi posts a comment on the PR pointing the contributor to the Fix & Re-push workflow.
+
+#### Repositories
+
+| Command | What it does |
+|---------|-------------|
+| Create | Create a new repo (personal or org) |
+| Delete | Delete a repository |
+| Clone | Clone a repo locally |
+| Info | Show repo stats (stars, forks, issues, language) |
+| Topics | Set repository topics |
+| List | List all repos for a user or org |
+
+#### Contributors
+
+| Command | What it does |
+|---------|-------------|
+| Score Applicants | Score everyone who commented on an issue based on GitHub profile, PR history, and activity |
+| Rank | Sort and display ranked contributors |
+| Assign Best | Auto-assign the highest-scoring S or A tier applicant |
+
+#### Releases
+
+| Command | What it does |
+|---------|-------------|
+| Create | Create a new GitHub release with tag and notes |
+| List | List existing releases |
+
+---
+
+### Organization / School Mode
+
+**Menu:** `npx gitpadi` → `🏫 Organization/School`
+
+Built for instructors managing student cohorts.
+
+#### Create Assignment
+
+Creates a GitHub issue with the assignment description, deadline, submission instructions, and grading rubric pre-filled.
+
+```
+? Assignment title: Build a REST API
+? Description: Create a Node.js REST API with CRUD endpoints...
+? Deadline: March 15, 2026
+? Expected files: src/routes.ts, src/models.ts, tests/
+```
+
+Students fork the repo, complete the work, and open a PR with `Fixes #<issue-number>`.
+
+#### Grade a PR
 
-GitPadi can run on every event in your repo. Just add a workflow file.
+Manually grade a specific PR from the terminal.
+
+```
+📊 Grade for @student1 — PR #15
+  Assignment: Build a REST API (#3)
+  Changes:    142 lines across 5 files
+  CI:         ✅ Passed
+  Tests:      2 file(s)
+
+  Score: 85/100 — Grade A 🟢
+
+✅ Grade posted to PR.
+? Merge this PR? ✅ Yes, squash & merge
+```
+
+#### Cohort Leaderboard
+
+Ranks all students by their average grade across all assignments.
+
+```
+🏆 COHORT LEADERBOARD
+
+| Rank | Student   | Avg Score | Assignments | Grades  |
+|------|-----------|-----------|-------------|---------|
+| 🥇   | @alice    | 88/100    | 3           | A, A, B |
+| 🥈   | @bob      | 72/100    | 3           | B, B, A |
+| 🥉   | @charlie  | 65/100    | 2           | B, C    |
+```
+
+Optionally posts the leaderboard to a pinned GitHub issue.
+
+---
+
+## Drop-in GitHub Actions
+
+Copy this into `.github/workflows/gitpadi.yml` — no other setup needed.
 
-**Auto-Score Applicants:**
 ```yaml
-- uses: Netwalls/contributor-agent@v2
-  with:
-    action: score-applicant
+# .github/workflows/gitpadi.yml
+# Copy this file to any repo — no setup needed.
+
+name: GitPadi
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  issue_comment:
+    types: [created]
+  schedule:
+    - cron: '0 9 * * *'
+  workflow_dispatch:
+    inputs:
+      action:
+        type: choice
+        options: [review-and-merge, create-issues, remind-contributors]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  review-pr:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Netwalls/contributor-agent@main
+        with:
+          action: review-pr
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+  score-applicant:
+    if: github.event_name == 'issue_comment'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Netwalls/contributor-agent@main
+        with:
+          action: score-applicant
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+  remind-contributors:
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Netwalls/contributor-agent@main
+        with:
+          action: remind-contributors
+          github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-**Auto-Review PRs:**
+### What each job does
+
+| Job | Trigger | What it does |
+|-----|---------|-------------|
+| `review-pr` | `pull_request` | Post automated PR review (size, tests, commit style, CI status) |
+| `score-applicant` | `issue_comment` | Score and rank applicants when someone comments on an issue |
+| `remind-contributors` | `schedule` (daily 9am) | Send tiered reminders to inactive assignees; auto-unassign at 72h |
+
+### Assignment mode opt-in
+
+To enable automatic assignment grading, add this environment variable to the `review-pr` job:
+
 ```yaml
-- uses: Netwalls/contributor-agent@v2
-  with:
-    action: review-pr
+  review-pr:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    env:
+      GITPADI_ASSIGNMENT_MODE: 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Netwalls/contributor-agent@main
+        with:
+          action: grade-assignment
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          pass-threshold: 40
 ```
 
+### All available actions
+
+| Action | Trigger | What it does |
+|--------|---------|-------------|
+| `review-pr` | `pull_request` | Automated PR quality review |
+| `review-and-merge` | `pull_request` | Review + CI check + auto-merge if passing |
+| `grade-assignment` | `pull_request` | Grade student submissions + post grade card + auto-merge |
+| `score-applicant` | `issue_comment` | Score and rank applicants on issues |
+| `remind-contributors` | `schedule` | Tiered reminders (24h/48h/72h) to inactive assignees |
+| `create-issues` | Manual/workflow | Bulk-create issues from a file |
+
+### All `with:` inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `action` | Yes | — | One of the actions listed above |
+| `github-token` | Yes | — | Use `${{ secrets.GITHUB_TOKEN }}` |
+| `auto-merge` | No | `false` | Auto-merge PR if CI passes and no critical issues |
+| `pass-threshold` | No | `40` | Minimum score (0–100) to auto-merge a graded assignment |
+| `anthropic-api-key` | No | — | Optional Claude API key for AI-enhanced reviews |
+
 ---
 
-## 📄 License
-MIT — Built by [Netwalls](https://github.com/Netwalls)
+## GitLab Support
+
+GitPadi v2.1 ships full GitLab support: a complete CLI for GitLab issues, MRs, and pipelines, plus 5 Duo External Agents powered by Claude AI.
+
+### GitLab CLI
+
+From the mode selector, choose **GitLab** to access:
+
+- **Issues** — list, create, close, assign, search, label
+- **Merge Requests** — list, review, merge, close, approve, diff
+- **Pipelines** — list pipeline runs, view job logs, retry failed jobs
+- **Repositories** — list, clone, fork, create
+
+### 5 Duo External Agents
+
+Add these to your GitLab project's Duo External Agent configuration:
+
+| Agent | What it does |
+|-------|-------------|
+| `contributor-scoring` | Score and rank applicants who comment on issues |
+| `mr-review` | Automated MR quality review and inline feedback |
+| `ci-recovery` | Diagnose pipeline failures and guide the contributor to a fix |
+| `reminder` | Escalating reminders for inactive assignees (24h→48h→72h) |
+| `grade-assignment` | Grade student MRs against the 5-criteria rubric |
+
+### `.gitlab-ci.yml` setup
+
+```yaml
+gitpadi-review:
+  image: node:20
+  script:
+    - npx gitpadi@latest ci-run
+  variables:
+    GITLAB_TOKEN: $GITLAB_TOKEN
+    AI_FLOW_AI_GATEWAY_TOKEN: $AI_FLOW_AI_GATEWAY_TOKEN
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+```
+
+### Environment variables for GitLab
+
+| Variable | Purpose |
+|----------|---------|
+| `GITLAB_TOKEN` | GitLab Personal Access Token (`glpat-...`) |
+| `GITLAB_HOST` | Your GitLab host (default: `https://gitlab.com`) |
+| `AI_FLOW_AI_GATEWAY_TOKEN` | GitLab AI Gateway token for Duo agents |
+| `ANTHROPIC_API_KEY` | Alternative: use your own Claude API key |
+
+---
+
+## Grading Rubric
+
+Student PRs are scored on 5 criteria totaling 100 points:
+
+| Criteria | Points | What's checked |
+|----------|--------|----------------|
+| CI Passing | 25 | All GitHub Actions checks are green |
+| Assignment Relevance | 25 | PR matches the assignment scope and issue description |
+| Test Coverage | 20 | Tests are included with source changes |
+| Code Quality | 15 | Clean commits, reasonable PR size, no obvious issues |
+| Submission Format | 15 | Branch name, issue reference (`Fixes #N`), PR body |
+
+Grade thresholds:
+
+| Grade | Score |
+|-------|-------|
+| A | 80 – 100 |
+| B | 60 – 79 |
+| C | 40 – 59 |
+| D | 20 – 39 |
+| F | 0 – 19 |
+
+---
+
+## Contributor Scoring
+
+When a maintainer runs **Score Applicants** (or the `score-applicant` Action fires), GitPadi evaluates everyone who commented on an issue.
+
+### Scoring factors
+
+- GitHub account age and activity
+- Number of merged PRs
+- Contribution quality and frequency
+- Relevance to the issue
+
+### Tiers
+
+| Tier | Meaning |
+|------|---------|
+| S | Exceptional — immediately eligible for auto-assign |
+| A | Strong — eligible for auto-assign |
+| B | Competent |
+| C | Developing |
+| D | Limited history |
+
+**Auto-assign behavior:** When `Assign Best` is triggered (CLI or Action), GitPadi picks the highest-scoring S or A tier applicant and assigns them to the issue.
+
+---
+
+## Escalating Reminders
+
+The `remind-contributors` action runs daily at 9am UTC (or on whatever schedule you configure). It checks every issue with an assigned contributor and escalates based on inactivity:
+
+| Time since assignment | Action |
+|-----------------------|--------|
+| 24 hours | Posts a friendly nudge: "Please create a draft PR to show progress" |
+| 48 hours (no draft PR) | Posts a warning: "You'll be unassigned in 24h if no PR is opened" |
+| 72 hours (still no PR) | Auto-unassigns the contributor and reopens the issue |
+
+GitPadi checks for linked draft PRs before escalating — contributors with a draft PR are never reminded. Unique comment signatures prevent duplicate posts.
+
+---
+
+## Configuration
+
+GitPadi stores config at `~/.gitpadi/config.json`:
+
+```json
+{
+  "token": "ghp_xxxxxxxxxxxx",
+  "gitlabToken": "glpat-xxxxxxxxxxxx",
+  "gitlabHost": "https://gitlab.com",
+  "owner": "your-org",
+  "repo": "your-repo"
+}
+```
+
+Environment variables take priority over the config file:
+
+| Variable | Purpose |
+|----------|---------|
+| `GITHUB_TOKEN` or `GITPADI_TOKEN` | GitHub authentication |
+| `GITHUB_OWNER` | Repository owner |
+| `GITHUB_REPO` | Repository name |
+| `GITLAB_TOKEN` | GitLab authentication |
+| `GITLAB_HOST` | GitLab instance URL |
+| `AI_FLOW_AI_GATEWAY_TOKEN` | GitLab AI Gateway token |
+| `ANTHROPIC_API_KEY` | Claude API key (optional enhancement) |
+
+GitPadi also auto-detects the repository from your local `.git/config` when run inside a git directory.
+
+---
+
+## Changelog
+
+### v2.1.0
+
+**GitLab**
+- Full GitLab CLI: issues, MRs, pipelines, repositories
+- 5 Duo External Agents: `contributor-scoring`, `mr-review`, `ci-recovery`, `reminder`, `grade-assignment`
+- GitLab authentication flow with host + `glpat-` token
+
+**GitHub**
+- Auto-assign: top S/A tier contributor automatically assigned after scoring
+- Auto-close: linked issues automatically closed when PR is merged
+- `score-applicant` Action now triggers on `issue_comment` events
+
+### v2.0.0
+
+**Contributor**
+- Fix & Re-push workflow for CI failures
+- Reply to maintainer comments from the terminal
+
+**Maintainer**
+- Review & Merge: review PR + CI check + squash merge in one flow
+- `review-and-merge` GitHub Action with `auto-merge` support
+
+**Organization / School**
+- Third CLI mode: Create Assignment, Grade PR, Cohort Leaderboard
+- `grade-assignment` GitHub Action with 5-criteria scoring and auto-merge
+- Grade card posted as a PR comment with full breakdown
+
+**Reminders**
+- Upgraded from flat 2-day poke to 3-tier escalation (24h → 48h → 72h)
+- Draft PR detection: skips reminders if contributor has a linked PR
+- Auto-unassign at 72h
+
+### v1.0.0
+
+**Contributor**
+- Fork & Clone automation
+- Upstream sync (API sync + local merge)
+- CI log viewer
+- One-command PR submission with auto-detected issue metadata
+
+**Maintainer**
+- Full issue management (create, close, reopen, delete, assign, search, label, bulk-create)
+- Pull request management (list, merge, close, review, approve, diff)
+- Repository management (create, delete, clone, info, topics, list)
+- Contributor scoring and ranking
+- Release management
+
+**GitHub Actions**
+- `create-issues` — bulk issue creation from file
+- `review-pr` — automated PR quality review
+- `score-applicant` — contributor scoring on issues
+- `remind-contributors` — automated contributor reminders
+
+---
+
+## License
+
+MIT — [Netwalls](https://github.com/Netwalls)