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:
@@ -1,114 +1,461 @@
|
||||
---
|
||||
description: Run initial setup for projman plugin
|
||||
description: Interactive setup wizard for projman plugin - configures MCP servers, credentials, and project settings
|
||||
---
|
||||
|
||||
# Initial Setup
|
||||
# Initial Setup Wizard
|
||||
|
||||
Run the installation script to set up the projman plugin.
|
||||
This command guides the user through complete projman setup interactively. It handles both first-time marketplace setup and per-project configuration.
|
||||
|
||||
## What This Does
|
||||
## Important Context
|
||||
|
||||
1. Creates Python virtual environments for MCP servers
|
||||
2. Installs all dependencies
|
||||
3. Creates configuration file templates
|
||||
4. Validates existing configuration
|
||||
5. Validates repository organization
|
||||
6. Syncs label taxonomy
|
||||
7. Reports remaining manual steps
|
||||
- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
|
||||
- **MCP tools won't work until after setup + session restart**
|
||||
- **Tokens must be entered manually by the user** for security (not typed into chat)
|
||||
|
||||
## Execution
|
||||
---
|
||||
|
||||
## Quick Path Detection
|
||||
|
||||
**FIRST**, check if system-level setup is already complete:
|
||||
|
||||
```bash
|
||||
cd ${PROJECT_ROOT}
|
||||
./scripts/setup.sh
|
||||
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep -v "example.com" | grep "GITEA_TOKEN=" && echo "SYSTEM_CONFIGURED" || echo "SYSTEM_NEEDS_SETUP"
|
||||
```
|
||||
|
||||
## Configuration Structure
|
||||
**If SYSTEM_CONFIGURED:**
|
||||
|
||||
The plugin uses a hybrid configuration approach:
|
||||
The system-level configuration already exists. Offer the user a choice:
|
||||
|
||||
**System-Level (credentials):**
|
||||
Use AskUserQuestion:
|
||||
- Question: "System configuration found. What would you like to do?"
|
||||
- Header: "Setup Mode"
|
||||
- Options:
|
||||
- "Quick project setup only (Recommended for new projects)"
|
||||
- "Full setup (re-check everything)"
|
||||
|
||||
**If "Quick project setup":**
|
||||
- Skip directly to **Phase 4: Project-Level Configuration**
|
||||
- This is equivalent to running `/project-init`
|
||||
|
||||
**If "Full setup":**
|
||||
- Continue with Phase 1 below
|
||||
|
||||
**If SYSTEM_NEEDS_SETUP:**
|
||||
- Continue with Phase 1 (full setup required)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Environment Validation
|
||||
|
||||
### Step 1.1: Check Python Version
|
||||
|
||||
Run this command to verify Python 3.10+ is available:
|
||||
|
||||
```bash
|
||||
python3 --version
|
||||
```
|
||||
~/.config/claude/gitea.env
|
||||
|
||||
**If version is below 3.10:**
|
||||
- Stop setup and inform user: "Python 3.10 or higher is required. Please install it and run /initial-setup again."
|
||||
- Provide installation hints based on OS (apt, brew, etc.)
|
||||
|
||||
**If successful:** Continue to next step.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: MCP Server Setup
|
||||
|
||||
### Step 2.1: Locate the Plugin Installation
|
||||
|
||||
The plugin is installed somewhere on the system. Find the MCP server directory by resolving the path.
|
||||
|
||||
First, identify where this plugin is installed. The MCP server should be accessible via the symlink structure. Look for the gitea MCP server:
|
||||
|
||||
```bash
|
||||
# Find the plugin's mcp-servers directory (search common locations)
|
||||
find ~/.claude ~/.config/claude -name "mcp_server" -path "*gitea*" 2>/dev/null | head -5
|
||||
```
|
||||
Contains API credentials that work across all projects.
|
||||
|
||||
**Project-Level (repository/paths):**
|
||||
If found, extract the parent path (the gitea MCP server root).
|
||||
|
||||
**Alternative:** If the user knows the marketplace location, ask them:
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Where is the Leo Claude Marketplace installed?"
|
||||
- Options:
|
||||
- "~/.claude/plugins/leo-claude-mktplace" (default Claude plugins location)
|
||||
- "Let me find it automatically"
|
||||
- Other (user provides path)
|
||||
|
||||
### Step 2.2: Check if Virtual Environment Exists
|
||||
|
||||
Once you have the MCP server path (e.g., `/path/to/mcp-servers/gitea`), check for the venv:
|
||||
|
||||
```bash
|
||||
ls -la /path/to/mcp-servers/gitea/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING"
|
||||
```
|
||||
project-root/.env
|
||||
|
||||
### Step 2.3: Create Virtual Environment (if missing)
|
||||
|
||||
If venv doesn't exist:
|
||||
|
||||
```bash
|
||||
cd /path/to/mcp-servers/gitea && python3 -m venv .venv
|
||||
```
|
||||
Contains project-specific settings like repository name.
|
||||
|
||||
## After Running
|
||||
Then install dependencies:
|
||||
|
||||
Review the output for any manual steps required:
|
||||
```bash
|
||||
cd /path/to/mcp-servers/gitea && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
|
||||
```
|
||||
|
||||
1. **Configure API credentials** in `~/.config/claude/gitea.env`:
|
||||
**If pip install fails:**
|
||||
- Show the error to the user
|
||||
- Suggest: "Check your internet connection and try again. You can also manually run: `cd /path/to/mcp-servers/gitea && source .venv/bin/activate && pip install -r requirements.txt`"
|
||||
|
||||
### Step 2.4: NetBox MCP Server (Optional)
|
||||
|
||||
Check if the user wants to set up the NetBox MCP server (for cmdb-assistant plugin):
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Do you want to set up the NetBox MCP server for infrastructure management?"
|
||||
- Options:
|
||||
- "Yes, set up NetBox MCP"
|
||||
- "No, skip NetBox (Recommended if not using cmdb-assistant)"
|
||||
|
||||
If yes, repeat steps 2.2-2.3 for `/path/to/mcp-servers/netbox`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: System-Level Configuration
|
||||
|
||||
System configuration is stored in `~/.config/claude/` and contains credentials that work across all projects.
|
||||
|
||||
### Step 3.1: Create Config Directory
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/claude
|
||||
```
|
||||
|
||||
### Step 3.2: Check Gitea Configuration
|
||||
|
||||
```bash
|
||||
cat ~/.config/claude/gitea.env 2>/dev/null || echo "FILE_NOT_FOUND"
|
||||
```
|
||||
|
||||
**If file doesn't exist:** Go to Step 3.3 (Create Template)
|
||||
**If file exists:** Read it and check if values are placeholders (contain "example.com" or "your_" or "token_here"). If placeholders, go to Step 3.4 (Update Existing).
|
||||
**If file has real values:** Go to Step 3.5 (Validate).
|
||||
|
||||
### Step 3.3: Create Gitea Configuration Template
|
||||
|
||||
Gather the Gitea server URL from the user.
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "What is your Gitea server URL? (e.g., https://gitea.company.com)"
|
||||
- Header: "Gitea URL"
|
||||
- Options:
|
||||
- "https://gitea.hotserv.cloud" (if this is Leo's setup)
|
||||
- "Other (I'll provide the URL)"
|
||||
|
||||
If "Other", ask the user to type the URL.
|
||||
|
||||
Now create the configuration file with a placeholder for the token:
|
||||
|
||||
```bash
|
||||
cat > ~/.config/claude/gitea.env << 'EOF'
|
||||
# Gitea API Configuration
|
||||
# Generated by /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
|
||||
```
|
||||
|
||||
Replace `<USER_PROVIDED_URL>` with the actual value from the user.
|
||||
|
||||
### Step 3.4: Token Entry Instructions
|
||||
|
||||
**CRITICAL: Do not ask the user to type the token into chat.**
|
||||
|
||||
Display these instructions clearly:
|
||||
|
||||
---
|
||||
|
||||
**Action Required: Add Your Gitea API Token**
|
||||
|
||||
I've created the configuration file at `~/.config/claude/gitea.env` but you need to add your API token manually for security.
|
||||
|
||||
**Steps:**
|
||||
1. Open the file in your editor:
|
||||
```
|
||||
GITEA_URL=https://gitea.your-company.com
|
||||
GITEA_TOKEN=your-api-token
|
||||
GITEA_ORG=your-organization
|
||||
nano ~/.config/claude/gitea.env
|
||||
```
|
||||
Or use any editor you prefer.
|
||||
|
||||
2. **Configure project settings** in `.env`:
|
||||
```
|
||||
GITEA_REPO=your-repo-name
|
||||
WIKIJS_PROJECT=your-project
|
||||
```
|
||||
2. Generate a Gitea token (if you don't have one):
|
||||
- Go to your Gitea instance → User Icon → Settings
|
||||
- Click "Applications" tab
|
||||
- Under "Manage Access Tokens", click "Generate New Token"
|
||||
- Name it something like "claude-code"
|
||||
- Select permissions: `repo` (all), `read:org`, `read:user`
|
||||
- Click "Generate Token" and copy it immediately
|
||||
|
||||
3. **Run `/labels-sync`** to sync Gitea labels
|
||||
3. Replace `PASTE_YOUR_TOKEN_HERE` with your actual token
|
||||
|
||||
4. **Verify Gitea Wiki** is accessible and has proper structure
|
||||
4. Save the file
|
||||
|
||||
## Pre-Flight Checks
|
||||
---
|
||||
|
||||
The setup script validates:
|
||||
Use AskUserQuestion:
|
||||
- Question: "Have you added your Gitea token to ~/.config/claude/gitea.env?"
|
||||
- Header: "Token Added?"
|
||||
- Options:
|
||||
- "Yes, I've added the token"
|
||||
- "I need help generating a token"
|
||||
- "Skip for now (I'll do it later)"
|
||||
|
||||
- Repository belongs to an organization (required)
|
||||
- Required label categories exist
|
||||
- API credentials are valid
|
||||
- Network connectivity to Gitea
|
||||
**If "I need help":** Provide detailed instructions for their specific Gitea instance.
|
||||
**If "Skip":** Warn that MCP tools won't work until configured, but continue with project setup.
|
||||
|
||||
## Re-Running
|
||||
### Step 3.5: Validate Gitea Configuration
|
||||
|
||||
This command is safe to run multiple times. It will skip already-completed steps.
|
||||
Read the config file and verify it has non-placeholder values:
|
||||
|
||||
## MCP Server Structure
|
||||
|
||||
The plugin bundles these MCP servers:
|
||||
|
||||
```
|
||||
plugins/projman/mcp-servers/
|
||||
└── gitea/
|
||||
├── .venv/
|
||||
├── requirements.txt
|
||||
└── mcp_server/
|
||||
├── server.py
|
||||
├── gitea_client.py
|
||||
└── tools/
|
||||
├── issues.py
|
||||
├── labels.py
|
||||
├── wiki.py
|
||||
├── milestones.py
|
||||
└── dependencies.py
|
||||
```bash
|
||||
source ~/.config/claude/gitea.env && echo "URL: $GITEA_URL" && echo "ORG: $GITEA_ORG" && echo "TOKEN_LENGTH: ${#GITEA_TOKEN}"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
If TOKEN_LENGTH is less than 10 or contains "PASTE" or "your_", the token hasn't been set properly.
|
||||
|
||||
**Error: Repository not under organization**
|
||||
- This plugin requires repositories to belong to a Gitea organization
|
||||
- Transfer your repository to an organization or create one
|
||||
**Test connectivity (optional but recommended):**
|
||||
|
||||
**Error: Missing required labels**
|
||||
- Run `/labels-sync` to create missing labels
|
||||
- Or create them manually in Gitea
|
||||
```bash
|
||||
source ~/.config/claude/gitea.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
|
||||
```
|
||||
|
||||
**Error: Cannot connect to Gitea**
|
||||
- Verify `GITEA_URL` in `~/.config/claude/gitea.env`
|
||||
- Check your API token has proper permissions
|
||||
- Ensure network connectivity
|
||||
- **200:** Success! Credentials are valid.
|
||||
- **401:** Invalid token.
|
||||
- **404/Connection error:** Invalid URL or network issue.
|
||||
|
||||
**Error: Virtual environment creation failed**
|
||||
- Ensure Python 3.8+ is installed
|
||||
- Check disk space
|
||||
- Try running `python -m venv .venv` manually in the MCP server directory
|
||||
Report the result to the user.
|
||||
|
||||
### Step 3.6: Git-Flow Configuration (Optional)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Do you want to configure git-flow defaults for smart commits?"
|
||||
- Header: "Git-Flow"
|
||||
- Options:
|
||||
- "Yes, use recommended defaults (Recommended)"
|
||||
- "Yes, let me customize"
|
||||
- "No, skip git-flow configuration"
|
||||
|
||||
If yes with defaults:
|
||||
```bash
|
||||
cat > ~/.config/claude/git-flow.env << 'EOF'
|
||||
# Git-Flow Default Configuration
|
||||
GIT_WORKFLOW_STYLE=feature-branch
|
||||
GIT_DEFAULT_BASE=development
|
||||
GIT_AUTO_DELETE_MERGED=true
|
||||
GIT_AUTO_PUSH=false
|
||||
GIT_PROTECTED_BRANCHES=main,master,development,staging,production
|
||||
GIT_COMMIT_STYLE=conventional
|
||||
GIT_CO_AUTHOR=true
|
||||
EOF
|
||||
chmod 600 ~/.config/claude/git-flow.env
|
||||
```
|
||||
|
||||
If customize, use AskUserQuestion for each setting.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Project-Level Configuration
|
||||
|
||||
Project configuration is stored in `.env` in the current project root.
|
||||
|
||||
### Step 4.1: Verify Current Directory
|
||||
|
||||
Confirm we're in the right place:
|
||||
|
||||
```bash
|
||||
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
|
||||
```
|
||||
|
||||
If not a git repo, ask the user:
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "The current directory doesn't appear to be a git repository. Where should I create the project configuration?"
|
||||
- Options:
|
||||
- "This directory is correct, continue anyway"
|
||||
- "Let me navigate to the right directory first"
|
||||
|
||||
### Step 4.2: Check Existing Project Configuration
|
||||
|
||||
```bash
|
||||
cat .env 2>/dev/null || echo "FILE_NOT_FOUND"
|
||||
```
|
||||
|
||||
If `.env` exists and has `GITEA_REPO=` set to a non-placeholder value, skip to Phase 5.
|
||||
|
||||
### Step 4.3: Infer Organization and Repository from Git Remote
|
||||
|
||||
Try to detect org and repo name automatically:
|
||||
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null
|
||||
```
|
||||
|
||||
Parse the output to extract both organization and repository:
|
||||
- `git@gitea.example.com:org/repo-name.git` → org: `org`, repo: `repo-name`
|
||||
- `https://gitea.example.com/org/repo-name.git` → org: `org`, repo: `repo-name`
|
||||
|
||||
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 4.4: Validate Repository via Gitea API
|
||||
|
||||
**Before asking for confirmation**, verify the repository exists and is accessible:
|
||||
|
||||
```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>"
|
||||
```
|
||||
|
||||
**Based on response:**
|
||||
|
||||
| HTTP Code | Meaning | Action |
|
||||
|-----------|---------|--------|
|
||||
| **200** | Repository exists and accessible | **Auto-fill without asking** - skip to Step 4.7 |
|
||||
| **404** | Repository not found | Ask user to confirm/correct (Step 4.5) |
|
||||
| **401/403** | Token issue or no access | Warn about permissions, ask to confirm |
|
||||
| **Other** | Network/server issue | Warn, ask to confirm manually |
|
||||
|
||||
**If 200 OK:** Display confirmation message and skip to Step 4.7:
|
||||
"Verified: Repository '<detected-org>/<detected-repo>' exists and is accessible."
|
||||
|
||||
### Step 4.5: Confirm Organization (only if API validation failed)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Repository '<detected-org>/<detected-repo>' was not found. Is '<detected-org>' the correct organization?"
|
||||
- Header: "Organization"
|
||||
- Options:
|
||||
- "Yes, that's correct"
|
||||
- "No, let me specify the correct organization"
|
||||
|
||||
If no, ask user to provide the correct organization name.
|
||||
|
||||
### Step 4.6: Confirm Repository Name (only if API validation failed)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Is '<detected-repo-name>' the correct Gitea repository name?"
|
||||
- Header: "Repository"
|
||||
- Options:
|
||||
- "Yes, that's correct"
|
||||
- "No, let me specify the correct name"
|
||||
|
||||
If no, ask user to provide the correct name.
|
||||
|
||||
**After user provides corrections, re-validate via API (Step 4.4)** to ensure the corrected values are valid.
|
||||
|
||||
### Step 4.7: Create Project Configuration
|
||||
|
||||
```bash
|
||||
cat > .env << 'EOF'
|
||||
# Project Configuration for projman
|
||||
# Generated by /initial-setup
|
||||
|
||||
GITEA_ORG=<ORG_NAME>
|
||||
GITEA_REPO=<REPO_NAME>
|
||||
EOF
|
||||
```
|
||||
|
||||
Replace `<REPO_NAME>` with the confirmed value.
|
||||
|
||||
**Important:** Check if `.env` is in `.gitignore`:
|
||||
|
||||
```bash
|
||||
grep -q "^\.env$" .gitignore 2>/dev/null && echo "GITIGNORE_OK" || echo "GITIGNORE_MISSING"
|
||||
```
|
||||
|
||||
If not in `.gitignore`, warn the user:
|
||||
"Warning: `.env` is not in your `.gitignore`. Consider adding it to prevent accidentally committing credentials."
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Final Validation and Next Steps
|
||||
|
||||
### Step 5.1: Summary Report
|
||||
|
||||
Display a summary of what was configured:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ SETUP COMPLETE ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ MCP Server (Gitea): ✓ Installed ║
|
||||
║ System Config: ✓ ~/.config/claude/gitea.env ║
|
||||
║ Project Config: ✓ ./.env ║
|
||||
║ Gitea Connection: ✓ Verified (or ⚠ Not tested) ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
### Step 5.2: Session Restart Notice
|
||||
|
||||
**IMPORTANT:** Display this notice clearly:
|
||||
|
||||
---
|
||||
|
||||
**⚠️ Session Restart Required**
|
||||
|
||||
The MCP server has been configured but won't be available until you restart your Claude Code session.
|
||||
|
||||
**To complete setup:**
|
||||
1. Exit this Claude Code session (type `/exit` or close the terminal)
|
||||
2. Start a new Claude Code session in this project
|
||||
3. The Gitea MCP tools will now be available
|
||||
|
||||
**After restart, you can:**
|
||||
- Run `/labels-sync` to sync your label taxonomy
|
||||
- Run `/sprint-plan` to start planning
|
||||
- Use MCP tools like `list_issues`, `create_issue`, etc.
|
||||
|
||||
---
|
||||
|
||||
### Step 5.3: Troubleshooting Checklist
|
||||
|
||||
If something isn't working after restart, check:
|
||||
|
||||
1. **MCP server not found:** Verify venv exists at the expected path
|
||||
2. **Authentication failed:** Re-check token in `~/.config/claude/gitea.env`
|
||||
3. **Wrong repository:** Verify `GITEA_REPO` in `./.env` matches Gitea exactly
|
||||
4. **Network error:** Ensure Gitea URL is accessible from this machine
|
||||
|
||||
---
|
||||
|
||||
## Re-Running This Command
|
||||
|
||||
This command is safe to run multiple times:
|
||||
- Existing venvs are skipped (not recreated)
|
||||
- Existing config files are checked for validity
|
||||
- Only missing or placeholder values are updated
|
||||
- Project config can be regenerated for new projects
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Files Created
|
||||
|
||||
| File | Purpose | Contains |
|
||||
|------|---------|----------|
|
||||
| `~/.config/claude/gitea.env` | System credentials | URL, token, org |
|
||||
| `~/.config/claude/git-flow.env` | Git defaults | Workflow settings |
|
||||
| `./.env` | Project settings | Repository name |
|
||||
| `<mcp-server>/.venv/` | Python environment | Dependencies |
|
||||
|
||||
218
plugins/projman/commands/project-init.md
Normal file
218
plugins/projman/commands/project-init.md
Normal file
@@ -0,0 +1,218 @@
|
||||
---
|
||||
description: Quick project setup - configures only project-level settings (assumes system setup is complete)
|
||||
---
|
||||
|
||||
# Project Initialization
|
||||
|
||||
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 create the project `.env` file
|
||||
|
||||
**Use `/initial-setup` instead if:**
|
||||
- This is your first time using the plugin
|
||||
- MCP tools aren't working (might need system setup)
|
||||
|
||||
---
|
||||
|
||||
## Pre-Flight Check
|
||||
|
||||
### Step 1: Verify System Configuration Exists
|
||||
|
||||
Quickly verify system setup is complete:
|
||||
|
||||
```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:**
|
||||
|
||||
Display this message and stop:
|
||||
|
||||
---
|
||||
|
||||
**System configuration not found or incomplete.**
|
||||
|
||||
It looks like the system-level setup hasn't been completed yet. Please run:
|
||||
|
||||
```
|
||||
/initial-setup
|
||||
```
|
||||
|
||||
This will configure both system credentials and this project.
|
||||
|
||||
---
|
||||
|
||||
**If SYSTEM_OK:** Continue to project setup.
|
||||
|
||||
---
|
||||
|
||||
## Project Setup
|
||||
|
||||
### Step 2: Verify Current Directory
|
||||
|
||||
```bash
|
||||
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
|
||||
```
|
||||
|
||||
If not a git repo, ask:
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "This doesn't appear to be a git repository. Continue anyway?"
|
||||
- Header: "Directory"
|
||||
- Options:
|
||||
- "Yes, continue here"
|
||||
- "No, I'll navigate to the correct directory"
|
||||
|
||||
### Step 3: Check for Existing Configuration
|
||||
|
||||
```bash
|
||||
cat .env 2>/dev/null | grep "GITEA_REPO=" || echo "NOT_CONFIGURED"
|
||||
```
|
||||
|
||||
**If already configured:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "This project already has GITEA_ORG and GITEA_REPO configured. What would you like to do?"
|
||||
- Header: "Existing"
|
||||
- Options:
|
||||
- "Keep existing configuration"
|
||||
- "Reconfigure (replace current settings)"
|
||||
|
||||
**If "Keep":** End with success message.
|
||||
|
||||
### Step 4: Detect Organization and Repository
|
||||
|
||||
Try to auto-detect from git remote:
|
||||
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
Verify the repository exists and is accessible:
|
||||
|
||||
```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 - display "Verified: <org>/<repo> exists" and skip to Step 8 |
|
||||
| **404** | Repository not found - proceed to Step 6 |
|
||||
| **401/403** | Permission issue - warn and proceed to Step 6 |
|
||||
|
||||
### Step 6: Confirm Organization (only if API 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"
|
||||
|
||||
If "No", ask user to type the correct organization name.
|
||||
|
||||
### Step 7: Confirm Repository Name (only if API validation failed)
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Is '<detected-repo-name>' the correct repository name?"
|
||||
- Header: "Repository"
|
||||
- Options:
|
||||
- "Yes, that's correct"
|
||||
- "No, let me specify"
|
||||
|
||||
If "No", ask user to type the correct name.
|
||||
|
||||
**After corrections, re-validate via API (Step 5).**
|
||||
|
||||
### Step 8: Create/Update Project Configuration
|
||||
|
||||
**If `.env` exists:**
|
||||
Check if it already has other content and append:
|
||||
|
||||
```bash
|
||||
echo "" >> .env
|
||||
echo "# Added by /project-init" >> .env
|
||||
echo "GITEA_ORG=<ORG_NAME>" >> .env
|
||||
echo "GITEA_REPO=<REPO_NAME>" >> .env
|
||||
```
|
||||
|
||||
**If `.env` doesn't exist:**
|
||||
|
||||
```bash
|
||||
cat > .env << 'EOF'
|
||||
# Project Configuration for projman
|
||||
# Generated by /project-init
|
||||
|
||||
GITEA_ORG=<ORG_NAME>
|
||||
GITEA_REPO=<REPO_NAME>
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 9: Check .gitignore
|
||||
|
||||
```bash
|
||||
grep -q "^\.env$" .gitignore 2>/dev/null && echo "GITIGNORE_OK" || echo "GITIGNORE_MISSING"
|
||||
```
|
||||
|
||||
**If GITIGNORE_MISSING:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "`.env` is not in `.gitignore`. Add it to prevent committing secrets?"
|
||||
- Header: "gitignore"
|
||||
- Options:
|
||||
- "Yes, add .env to .gitignore (Recommended)"
|
||||
- "No, I'll handle it manually"
|
||||
|
||||
If yes:
|
||||
```bash
|
||||
echo ".env" >> .gitignore
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete
|
||||
|
||||
Display success message:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ PROJECT CONFIGURED ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ Organization: <ORG_NAME> ║
|
||||
║ Repository: <REPO_NAME> ║
|
||||
║ Config file: ./.env ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
|
||||
You're ready to use projman commands:
|
||||
• /sprint-plan - Start sprint planning
|
||||
• /sprint-status - Check progress
|
||||
• /labels-sync - Sync label taxonomy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**MCP tools not working?**
|
||||
- Run `/initial-setup` for full setup including MCP server
|
||||
- Restart your Claude Code session after setup
|
||||
|
||||
**Wrong repository configured?**
|
||||
- Edit `.env` directly: `nano .env`
|
||||
- Or run `/project-init` again and choose "Reconfigure"
|
||||
196
plugins/projman/commands/project-sync.md
Normal file
196
plugins/projman/commands/project-sync.md
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
description: Sync project configuration with current git remote - use after changing repository location or organization
|
||||
---
|
||||
|
||||
# Project Sync
|
||||
|
||||
Updates project configuration when the git remote URL has changed (repository moved, renamed, or organization changed).
|
||||
|
||||
**Use this when:**
|
||||
- You moved the repository to a different organization
|
||||
- You renamed the repository
|
||||
- You changed the git remote URL
|
||||
- The 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:** Stop and instruct user to run `/initial-setup` first.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Read Current Configuration
|
||||
|
||||
Read the current .env values:
|
||||
|
||||
```bash
|
||||
cat .env 2>/dev/null
|
||||
```
|
||||
|
||||
Extract current values:
|
||||
- `CURRENT_ORG` from `GITEA_ORG=...`
|
||||
- `CURRENT_REPO` from `GITEA_REPO=...`
|
||||
|
||||
**If .env doesn't exist or has no GITEA values:** Redirect to `/project-init`.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Detect Git Remote Values
|
||||
|
||||
Get the current git remote:
|
||||
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null
|
||||
```
|
||||
|
||||
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 4: Compare Values
|
||||
|
||||
Compare current .env values with detected git remote values:
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| **Both match** | Display "Configuration is in sync" and exit |
|
||||
| **Organization changed** | Proceed to Step 5 |
|
||||
| **Repository changed** | Proceed to Step 5 |
|
||||
| **Both changed** | Proceed to Step 5 |
|
||||
|
||||
**If already in sync:**
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ CONFIGURATION IN SYNC ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ Organization: <ORG_NAME> ║
|
||||
║ Repository: <REPO_NAME> ║
|
||||
║ Git Remote: matches .env ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
Exit here if in sync.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Show Detected Changes
|
||||
|
||||
Display the detected changes to the user:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ REPOSITORY CHANGE DETECTED ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ Current .env │ Git Remote ║
|
||||
║ Organization: <OLD_ORG> │ <NEW_ORG> ║
|
||||
║ Repository: <OLD_REPO> │ <NEW_REPO> ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Validate New Repository via Gitea API
|
||||
|
||||
Verify the new repository exists and is accessible:
|
||||
|
||||
```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>"
|
||||
```
|
||||
|
||||
| HTTP Code | Action |
|
||||
|-----------|--------|
|
||||
| **200** | Repository verified - proceed to Step 7 |
|
||||
| **404** | Repository not found - ask user to confirm (Step 6a) |
|
||||
| **401/403** | Permission issue - warn and ask to confirm |
|
||||
|
||||
### Step 6a: Confirm if API Validation Failed
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "The new repository '<NEW_ORG>/<NEW_REPO>' was not found via API. Update configuration anyway?"
|
||||
- Header: "Not Found"
|
||||
- Options:
|
||||
- "Yes, update anyway (I'll fix the remote later)"
|
||||
- "No, let me fix the git remote first"
|
||||
- "Let me specify different values"
|
||||
|
||||
**If "specify different values":** Ask for correct org and repo, then re-validate.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Confirm Update
|
||||
|
||||
Use AskUserQuestion:
|
||||
- Question: "Update project configuration to match git remote?"
|
||||
- Header: "Confirm"
|
||||
- Options:
|
||||
- "Yes, update .env (Recommended)"
|
||||
- "No, keep current configuration"
|
||||
|
||||
**If "No":** Exit without changes.
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Update Configuration
|
||||
|
||||
Update the .env file with new values:
|
||||
|
||||
```bash
|
||||
# Update GITEA_ORG
|
||||
sed -i 's/^GITEA_ORG=.*/GITEA_ORG=<NEW_ORG>/' .env
|
||||
|
||||
# Update GITEA_REPO
|
||||
sed -i 's/^GITEA_REPO=.*/GITEA_REPO=<NEW_REPO>/' .env
|
||||
```
|
||||
|
||||
Alternatively, if sed doesn't work well, read the file, replace values, and write back.
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Verify Update
|
||||
|
||||
Read the updated .env and display confirmation:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ CONFIGURATION UPDATED ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ Organization: <NEW_ORG> ║
|
||||
║ Repository: <NEW_REPO> ║
|
||||
║ Status: In sync with git remote ║
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
|
||||
Your project configuration has been updated.
|
||||
MCP tools will now use the new repository.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"Repository not found" but it exists:**
|
||||
- Check your Gitea token has access to the new organization
|
||||
- Verify the repository name matches exactly (case-sensitive)
|
||||
- Ensure your token has `repo` permissions
|
||||
|
||||
**Git remote URL is wrong:**
|
||||
- Fix it first: `git remote set-url origin <correct-url>`
|
||||
- Then run `/project-sync` again
|
||||
|
||||
**Want to revert the change:**
|
||||
- Edit `.env` manually: `nano .env`
|
||||
- Or run `/project-sync` after fixing the git remote
|
||||
Reference in New Issue
Block a user