feat: add interactive setup wizard with API validation and mismatch detection
Major improvements to plugin setup experience: Setup Commands: - Redesign /initial-setup as interactive wizard (MCP + system + project config) - Add /project-init for quick project-only setup - Add /project-sync for handling repository moves/renames - Add Gitea API validation to auto-fill org/repo when verified Configuration Changes: - Move GITEA_ORG from system to project level (supports multi-org users) - System config now only contains GITEA_URL and GITEA_TOKEN - Project .env now contains GITEA_ORG and GITEA_REPO Automation: - Add SessionStart hook for projman and pr-review - Automatically detects git remote vs .env mismatch - Warns user to run /project-sync when mismatch found Documentation: - Unify configuration docs (remove duplicate in plugins/projman) - Add flow diagrams to CONFIGURATION.md - Add setup script review guidance to UPDATING.md - Update COMMANDS-CHEATSHEET.md with new commands and hooks Files added: - plugins/projman/commands/project-init.md - plugins/projman/commands/project-sync.md - plugins/projman/hooks/hooks.json - plugins/pr-review/commands/initial-setup.md - plugins/pr-review/commands/project-init.md - plugins/pr-review/commands/project-sync.md - plugins/pr-review/hooks/hooks.json - plugins/cmdb-assistant/commands/initial-setup.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
273
plugins/pr-review/commands/initial-setup.md
Normal file
273
plugins/pr-review/commands/initial-setup.md
Normal file
@@ -0,0 +1,273 @@
|
||||
---
|
||||
description: Interactive setup wizard for pr-review plugin - configures Gitea MCP and project settings
|
||||
---
|
||||
|
||||
# PR Review Setup Wizard
|
||||
|
||||
This command sets up the pr-review plugin. It shares the Gitea MCP server with projman, so if you've already run `/initial-setup` for projman, most of the work is done.
|
||||
|
||||
## Important Context
|
||||
|
||||
- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
|
||||
- **MCP tools won't work until after setup + session restart**
|
||||
- **Shares Gitea MCP server with projman plugin**
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Check Existing Setup
|
||||
|
||||
### Step 1.1: Check if Gitea MCP is Already Configured
|
||||
|
||||
First, check if the system configuration already exists (from projman or previous setup):
|
||||
|
||||
```bash
|
||||
cat ~/.config/claude/gitea.env 2>/dev/null || echo "FILE_NOT_FOUND"
|
||||
```
|
||||
|
||||
**If file exists with valid values (no placeholders):**
|
||||
- Skip to Phase 3 (Project Configuration)
|
||||
- Inform user: "Gitea configuration found. Skipping system setup."
|
||||
|
||||
**If file doesn't exist or has placeholders:**
|
||||
- Continue to Phase 2
|
||||
|
||||
### Step 1.2: Check if projman is Installed
|
||||
|
||||
Check if projman plugin exists (they share MCP server):
|
||||
|
||||
```bash
|
||||
find ~/.claude ~/.config/claude -name "projman" -type d 2>/dev/null | head -1
|
||||
```
|
||||
|
||||
**If projman exists:**
|
||||
- Suggest: "The projman plugin is installed and shares the same Gitea MCP server. Consider running `/initial-setup` from projman for the full setup wizard."
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "How would you like to proceed with setup?"
|
||||
- Header: "Setup"
|
||||
- Options:
|
||||
- "Continue with pr-review setup (Recommended if not using projman)"
|
||||
- "I'll use projman's /initial-setup instead"
|
||||
|
||||
**If user chooses projman setup:** End here with instructions to run projman's setup.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: System Setup (if needed)
|
||||
|
||||
This is a condensed version focusing on what pr-review needs.
|
||||
|
||||
### Step 2.1: Python and MCP Server
|
||||
|
||||
Check Python version:
|
||||
```bash
|
||||
python3 --version
|
||||
```
|
||||
|
||||
If below 3.10, stop and inform user.
|
||||
|
||||
Locate and set up the MCP server:
|
||||
```bash
|
||||
find ~/.claude ~/.config/claude -name "mcp_server" -path "*gitea*" 2>/dev/null | head -5
|
||||
```
|
||||
|
||||
If venv doesn't exist, create it:
|
||||
```bash
|
||||
cd /path/to/mcp-servers/gitea && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
|
||||
```
|
||||
|
||||
### Step 2.2: Gitea Configuration
|
||||
|
||||
Create config directory:
|
||||
```bash
|
||||
mkdir -p ~/.config/claude
|
||||
```
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "What is your Gitea server URL?"
|
||||
- Header: "Gitea URL"
|
||||
- Options:
|
||||
- "https://gitea.hotserv.cloud"
|
||||
- "Other (I'll provide the URL)"
|
||||
|
||||
Create configuration file (credentials only, org is per-project):
|
||||
```bash
|
||||
cat > ~/.config/claude/gitea.env << 'EOF'
|
||||
# Gitea API Configuration
|
||||
# Generated by pr-review /initial-setup
|
||||
# Note: GITEA_ORG is configured per-project in .env
|
||||
|
||||
GITEA_URL=<USER_PROVIDED_URL>
|
||||
GITEA_TOKEN=PASTE_YOUR_TOKEN_HERE
|
||||
EOF
|
||||
chmod 600 ~/.config/claude/gitea.env
|
||||
```
|
||||
|
||||
### Step 2.3: Token Instructions
|
||||
|
||||
Display these instructions:
|
||||
|
||||
---
|
||||
|
||||
**Action Required: Add Your Gitea API Token**
|
||||
|
||||
I've created `~/.config/claude/gitea.env` but you need to add your API token manually.
|
||||
|
||||
**Steps:**
|
||||
1. Open: `nano ~/.config/claude/gitea.env`
|
||||
2. Generate token in Gitea: Settings → Applications → Generate New Token
|
||||
- Permissions needed: `repo`, `read:org`, `read:user`
|
||||
3. Replace `PASTE_YOUR_TOKEN_HERE` with your token
|
||||
4. Save the file
|
||||
|
||||
---
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Have you added your Gitea token?"
|
||||
- Header: "Token"
|
||||
- Options:
|
||||
- "Yes, I've added the token"
|
||||
- "Skip for now"
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Project Configuration
|
||||
|
||||
### Step 3.1: Check Current Directory
|
||||
|
||||
```bash
|
||||
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
|
||||
```
|
||||
|
||||
### Step 3.2: Check Existing Project Config
|
||||
|
||||
```bash
|
||||
cat .env 2>/dev/null | grep GITEA_REPO || echo "NOT_FOUND"
|
||||
```
|
||||
|
||||
If `GITEA_REPO` is already set, skip to Phase 4.
|
||||
|
||||
### Step 3.3: Detect Organization and Repository
|
||||
|
||||
Extract organization:
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
|
||||
```
|
||||
|
||||
Extract repository:
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
|
||||
```
|
||||
|
||||
### Step 3.4: Validate Repository via Gitea API
|
||||
|
||||
```bash
|
||||
source ~/.config/claude/gitea.env
|
||||
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<detected-org>/<detected-repo>"
|
||||
```
|
||||
|
||||
| HTTP Code | Action |
|
||||
|-----------|--------|
|
||||
| **200** | Auto-fill - "Verified: <org>/<repo> exists" - skip to Step 3.7 |
|
||||
| **404** | Not found - proceed to Step 3.5 |
|
||||
| **401/403** | Permission issue - warn, proceed to Step 3.5 |
|
||||
|
||||
### Step 3.5: Confirm Organization (only if validation failed)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Repository not found. Is '<detected-org>' the correct organization?"
|
||||
- Header: "Organization"
|
||||
- Options:
|
||||
- "Yes, that's correct"
|
||||
- "No, let me specify"
|
||||
|
||||
### Step 3.6: Confirm Repository (only if validation failed)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Is '<detected-repo-name>' the correct repository?"
|
||||
- Header: "Repository"
|
||||
- Options:
|
||||
- "Yes, that's correct"
|
||||
- "No, let me specify"
|
||||
|
||||
**After corrections, re-validate via API (Step 3.4).**
|
||||
|
||||
### Step 3.7: Create/Update Project Config
|
||||
|
||||
If `.env` exists, append:
|
||||
```bash
|
||||
echo "GITEA_ORG=<ORG_NAME>" >> .env
|
||||
echo "GITEA_REPO=<REPO_NAME>" >> .env
|
||||
```
|
||||
|
||||
If `.env` doesn't exist:
|
||||
```bash
|
||||
cat > .env << 'EOF'
|
||||
# Project Configuration
|
||||
GITEA_ORG=<ORG_NAME>
|
||||
GITEA_REPO=<REPO_NAME>
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 3.5: PR Review Settings (Optional)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Do you want to configure PR review settings?"
|
||||
- Header: "Settings"
|
||||
- Options:
|
||||
- "Use defaults (Recommended)"
|
||||
- "Let me customize"
|
||||
|
||||
If customize, ask about:
|
||||
- `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.5)
|
||||
- `PR_REVIEW_AUTO_SUBMIT` (default: false)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Validation and Next Steps
|
||||
|
||||
### Step 4.1: Test Configuration (if token was added)
|
||||
|
||||
```bash
|
||||
source ~/.config/claude/gitea.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
|
||||
```
|
||||
|
||||
Report result:
|
||||
- 200: Success
|
||||
- 401: Invalid token
|
||||
- Other: Connection issue
|
||||
|
||||
### Step 4.2: Summary
|
||||
|
||||
```
|
||||
╔════════════════════════════════════════════════════════════╗
|
||||
║ PR-REVIEW SETUP COMPLETE ║
|
||||
╠════════════════════════════════════════════════════════════╣
|
||||
║ MCP Server (Gitea): ✓ Ready ║
|
||||
║ System Config: ✓ ~/.config/claude/gitea.env ║
|
||||
║ Project Config: ✓ ./.env ║
|
||||
╚════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
### Step 4.3: Session Restart Notice
|
||||
|
||||
---
|
||||
|
||||
**⚠️ Session Restart Required**
|
||||
|
||||
Restart your Claude Code session for MCP tools to become available.
|
||||
|
||||
**After restart, you can:**
|
||||
- Run `/pr-review <PR_NUMBER>` to review a pull request
|
||||
- Run `/pr-summary <PR_NUMBER>` for a quick summary
|
||||
- Run `/pr-findings <PR_NUMBER>` to list actionable findings
|
||||
|
||||
---
|
||||
|
||||
## Available Commands After Setup
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/pr-review <number>` | Full multi-agent PR review with confidence scoring |
|
||||
| `/pr-summary <number>` | Quick PR summary |
|
||||
| `/pr-findings <number>` | List findings with severity and line numbers |
|
||||
136
plugins/pr-review/commands/project-init.md
Normal file
136
plugins/pr-review/commands/project-init.md
Normal file
@@ -0,0 +1,136 @@
|
||||
---
|
||||
description: Quick project setup - configures only project-level settings for PR review
|
||||
---
|
||||
|
||||
# Project Initialization (PR Review)
|
||||
|
||||
Fast setup for a new project when system-level configuration is already complete.
|
||||
|
||||
**Use this when:**
|
||||
- You've already run `/initial-setup` on this machine
|
||||
- You're starting work on a new project/repository
|
||||
- You just need to configure this project for PR reviews
|
||||
|
||||
---
|
||||
|
||||
## Pre-Flight Check
|
||||
|
||||
### Step 1: Verify System Configuration
|
||||
|
||||
```bash
|
||||
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING"
|
||||
```
|
||||
|
||||
**If SYSTEM_MISSING:**
|
||||
|
||||
---
|
||||
|
||||
**System configuration not found.**
|
||||
|
||||
Please run `/initial-setup` first to configure Gitea credentials.
|
||||
|
||||
---
|
||||
|
||||
**If SYSTEM_OK:** Continue.
|
||||
|
||||
---
|
||||
|
||||
## Project Setup
|
||||
|
||||
### Step 2: Verify Current Directory
|
||||
|
||||
```bash
|
||||
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
|
||||
```
|
||||
|
||||
### Step 3: Check Existing Configuration
|
||||
|
||||
```bash
|
||||
cat .env 2>/dev/null | grep "GITEA_REPO=" || echo "NOT_CONFIGURED"
|
||||
```
|
||||
|
||||
If already configured, ask if user wants to keep or reconfigure.
|
||||
|
||||
### Step 4: Detect Organization and Repository
|
||||
|
||||
Extract organization:
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
|
||||
```
|
||||
|
||||
Extract repository:
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
|
||||
```
|
||||
|
||||
### Step 5: Validate Repository via Gitea API
|
||||
|
||||
```bash
|
||||
source ~/.config/claude/gitea.env
|
||||
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<detected-org>/<detected-repo>"
|
||||
```
|
||||
|
||||
| HTTP Code | Action |
|
||||
|-----------|--------|
|
||||
| **200** | Auto-fill - "Verified: <org>/<repo> exists" - skip to Step 8 |
|
||||
| **404** | Not found - proceed to Step 6 |
|
||||
| **401/403** | Permission issue - warn, proceed to Step 6 |
|
||||
|
||||
### Step 6: Confirm Organization (only if validation failed)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Repository not found. Is '<detected-org>' the correct organization?"
|
||||
- Header: "Organization"
|
||||
- Options:
|
||||
- "Yes, that's correct"
|
||||
- "No, let me specify"
|
||||
|
||||
### Step 7: Confirm Repository (only if validation failed)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Is '<detected-repo-name>' the correct repository?"
|
||||
- Header: "Repository"
|
||||
- Options:
|
||||
- "Yes, that's correct"
|
||||
- "No, let me specify"
|
||||
|
||||
**After corrections, re-validate via API (Step 5).**
|
||||
|
||||
### Step 8: Create/Update .env
|
||||
|
||||
```bash
|
||||
echo "GITEA_ORG=<ORG_NAME>" >> .env
|
||||
echo "GITEA_REPO=<REPO_NAME>" >> .env
|
||||
```
|
||||
|
||||
### Step 9: Optional PR Review Settings
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Configure PR review settings?"
|
||||
- Header: "Settings"
|
||||
- Options:
|
||||
- "Use defaults (Recommended)"
|
||||
- "Customize settings"
|
||||
|
||||
If customize:
|
||||
- `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.5)
|
||||
- `PR_REVIEW_AUTO_SUBMIT` (default: false)
|
||||
|
||||
---
|
||||
|
||||
## Complete
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ PROJECT CONFIGURED ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ Organization: <ORG_NAME> ║
|
||||
║ Repository: <REPO_NAME> ║
|
||||
║ Config file: ./.env ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
|
||||
Ready to review PRs:
|
||||
• /pr-review <number> - Full multi-agent review
|
||||
• /pr-summary <number> - Quick summary
|
||||
• /pr-findings <number> - List findings
|
||||
```
|
||||
93
plugins/pr-review/commands/project-sync.md
Normal file
93
plugins/pr-review/commands/project-sync.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
description: Sync project configuration with current git remote - use after changing repository location
|
||||
---
|
||||
|
||||
# Project Sync (PR Review)
|
||||
|
||||
Updates project configuration when the git remote URL has changed.
|
||||
|
||||
**Use this when:**
|
||||
- Repository was moved to a different organization
|
||||
- Repository was renamed
|
||||
- Git remote URL changed
|
||||
- SessionStart hook detected a mismatch
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Verify System Configuration
|
||||
|
||||
```bash
|
||||
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING"
|
||||
```
|
||||
|
||||
**If SYSTEM_MISSING:** Run `/initial-setup` first.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Read Current .env
|
||||
|
||||
```bash
|
||||
cat .env 2>/dev/null
|
||||
```
|
||||
|
||||
Extract `GITEA_ORG` and `GITEA_REPO` values.
|
||||
|
||||
**If missing:** Redirect to `/project-init`.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Detect Git Remote
|
||||
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null
|
||||
```
|
||||
|
||||
Extract organization and repository from URL.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Compare Values
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| **Match** | "Configuration in sync" - exit |
|
||||
| **Mismatch** | Show diff, proceed to validation |
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Validate via Gitea API
|
||||
|
||||
```bash
|
||||
source ~/.config/claude/gitea.env
|
||||
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<NEW_ORG>/<NEW_REPO>"
|
||||
```
|
||||
|
||||
| Code | Action |
|
||||
|------|--------|
|
||||
| **200** | Verified - proceed to update |
|
||||
| **404** | Not found - ask to confirm |
|
||||
| **401/403** | Permission issue - warn |
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Confirm and Update
|
||||
|
||||
Use AskUserQuestion to confirm, then update .env:
|
||||
|
||||
```bash
|
||||
sed -i 's/^GITEA_ORG=.*/GITEA_ORG=<NEW_ORG>/' .env
|
||||
sed -i 's/^GITEA_REPO=.*/GITEA_REPO=<NEW_REPO>/' .env
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Confirm Success
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ CONFIGURATION UPDATED ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ Organization: <NEW_ORG> ║
|
||||
║ Repository: <NEW_REPO> ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
Reference in New Issue
Block a user