From 0c2fc8c0d9b26e67787345986b50f8cccb978f80 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 21 Jan 2026 11:20:36 -0500 Subject: [PATCH] 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 --- CLAUDE.md | 23 +- docs/COMMANDS-CHEATSHEET.md | 38 +- docs/CONFIGURATION.md | 591 +++++++++++------- docs/UPDATING.md | 118 +++- .../cmdb-assistant/commands/initial-setup.md | 160 +++++ plugins/pr-review/commands/initial-setup.md | 273 ++++++++ plugins/pr-review/commands/project-init.md | 136 ++++ plugins/pr-review/commands/project-sync.md | 93 +++ plugins/pr-review/hooks/hooks.json | 15 + plugins/projman/CONFIGURATION.md | 39 +- plugins/projman/README.md | 106 ++-- plugins/projman/commands/initial-setup.md | 499 ++++++++++++--- plugins/projman/commands/project-init.md | 218 +++++++ plugins/projman/commands/project-sync.md | 196 ++++++ plugins/projman/hooks/hooks.json | 15 + scripts/setup.sh | 13 +- 16 files changed, 2132 insertions(+), 401 deletions(-) create mode 100644 plugins/cmdb-assistant/commands/initial-setup.md create mode 100644 plugins/pr-review/commands/initial-setup.md create mode 100644 plugins/pr-review/commands/project-init.md create mode 100644 plugins/pr-review/commands/project-sync.md create mode 100644 plugins/pr-review/hooks/hooks.json create mode 100644 plugins/projman/commands/project-init.md create mode 100644 plugins/projman/commands/project-sync.md create mode 100644 plugins/projman/hooks/hooks.json diff --git a/CLAUDE.md b/CLAUDE.md index df043e8..8427a4e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,7 +28,12 @@ A plugin marketplace for Claude Code containing: # Validate marketplace compliance ./scripts/validate-marketplace.sh -# Run projman commands (in a target project with plugin installed) +# Setup commands (in a target project with plugin installed) +/initial-setup # First time: full setup wizard +/project-init # New project: quick config +/project-sync # After repo move: sync config + +# Run projman commands /sprint-plan # Start sprint planning /sprint-status # Check progress /review # Pre-close code quality review @@ -50,18 +55,20 @@ leo-claude-mktplace/ │ │ ├── .claude-plugin/plugin.json │ │ ├── .mcp.json │ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK -│ │ ├── commands/ # 9 commands +│ │ ├── commands/ # 12 commands (incl. setup) +│ │ ├── hooks/ # SessionStart mismatch detection │ │ ├── agents/ # 4 agents │ │ └── skills/label-taxonomy/ -│ ├── git-flow/ # Git workflow automation (NEW v3.0.0) +│ ├── git-flow/ # Git workflow automation │ │ ├── .claude-plugin/plugin.json │ │ ├── commands/ # 8 commands │ │ └── agents/ -│ ├── pr-review/ # Multi-agent PR review (NEW v3.0.0) +│ ├── pr-review/ # Multi-agent PR review │ │ ├── .claude-plugin/plugin.json │ │ ├── .mcp.json │ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK -│ │ ├── commands/ # 3 commands +│ │ ├── commands/ # 6 commands (incl. setup) +│ │ ├── hooks/ # SessionStart mismatch detection │ │ └── agents/ # 5 agents │ ├── clarity-assist/ # Prompt optimization (NEW v3.0.0) │ │ ├── .claude-plugin/plugin.json @@ -133,8 +140,10 @@ leo-claude-mktplace/ | Level | Location | Purpose | |-------|----------|---------| -| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN, GITEA_ORG) | -| Project | `.env` in project root | Repository specification (GITEA_REPO) | +| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN) | +| Project | `.env` in project root | Repository specification (GITEA_ORG, GITEA_REPO) | + +**Note:** `GITEA_ORG` is at project level since different projects may belong to different organizations. ### Branch-Aware Security diff --git a/docs/COMMANDS-CHEATSHEET.md b/docs/COMMANDS-CHEATSHEET.md index ee23b1a..44a1d54 100644 --- a/docs/COMMANDS-CHEATSHEET.md +++ b/docs/COMMANDS-CHEATSHEET.md @@ -15,7 +15,10 @@ Quick reference for all commands in the Leo Claude Marketplace. | **projman** | `/test-check` | | X | Run tests and verify coverage before sprint close | | **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki | | **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea | -| **projman** | `/initial-setup` | | X | Run installation script for projman plugin setup | +| **projman** | `/initial-setup` | | X | Full setup wizard: MCP server + system config + project config | +| **projman** | `/project-init` | | X | Quick project setup (assumes system config exists) | +| **projman** | `/project-sync` | | X | Sync config with git remote after repo move/rename | +| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run /project-sync | | **projman** | `/test-gen` | | X | Generate comprehensive tests for specified code | | **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message | | **git-flow** | `/commit-push` | | X | Commit and push to remote in one operation | @@ -25,6 +28,10 @@ Quick reference for all commands in the Leo Claude Marketplace. | **git-flow** | `/branch-cleanup` | | X | Remove merged branches locally and optionally on remote | | **git-flow** | `/git-status` | | X | Enhanced git status with recommendations | | **git-flow** | `/git-config` | | X | Configure git-flow settings for the project | +| **pr-review** | `/initial-setup` | | X | Setup wizard for pr-review (shares Gitea MCP with projman) | +| **pr-review** | `/project-init` | | X | Quick project setup for PR reviews | +| **pr-review** | `/project-sync` | | X | Sync config with git remote after repo move/rename | +| **pr-review** | *SessionStart hook* | X | | Detects git remote vs .env mismatch | | **pr-review** | `/pr-review` | | X | Full multi-agent PR review with confidence scoring | | **pr-review** | `/pr-summary` | | X | Quick summary of PR changes | | **pr-review** | `/pr-findings` | | X | List and filter review findings by category/severity | @@ -41,6 +48,7 @@ Quick reference for all commands in the Leo Claude Marketplace. | **claude-config-maintainer** | `/config-analyze` | | X | Analyze CLAUDE.md for optimization opportunities | | **claude-config-maintainer** | `/config-optimize` | | X | Optimize CLAUDE.md structure with preview/backup | | **claude-config-maintainer** | `/config-init` | | X | Initialize new CLAUDE.md for a project | +| **cmdb-assistant** | `/initial-setup` | | X | Setup wizard for NetBox MCP server | | **cmdb-assistant** | `/cmdb-search` | | X | Search NetBox for devices, IPs, sites | | **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) | | **cmdb-assistant** | `/cmdb-ip` | | X | Manage IP addresses and prefixes | @@ -53,6 +61,7 @@ Quick reference for all commands in the Leo Claude Marketplace. | Category | Plugins | Primary Use | |----------|---------|-------------| +| **Setup** | projman, pr-review, cmdb-assistant | `/initial-setup`, `/project-init` | | **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification | | **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews | | **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance | @@ -66,6 +75,8 @@ Quick reference for all commands in the Leo Claude Marketplace. | Plugin | Hook Event | Behavior | |--------|------------|----------| +| **projman** | SessionStart | Checks git remote vs .env; warns if mismatch detected | +| **pr-review** | SessionStart | Checks git remote vs .env; warns if mismatch detected | | **doc-guardian** | PostToolUse (Write/Edit) | Silently tracks documentation drift | | **doc-guardian** | Stop | Prompts to sync if drift detected | | **code-sentinel** | PreToolUse (Write/Edit) | Scans for security issues; blocks critical vulnerabilities | @@ -151,17 +162,32 @@ Managing infrastructure with CMDB: 4. /cmdb-site view Y # Check site info ``` -### Example 7: New Project Setup +### Example 7: First-Time Setup (New Machine) -Setting up a project with marketplace plugins: +Setting up the marketplace for the first time: ``` -1. /config-init # Create CLAUDE.md -2. /initial-setup # Setup projman (if using) +1. /initial-setup # Full setup: MCP + system config + project + # → Follow prompts for Gitea URL, org + # → Add token manually when prompted + # → Confirm repository name +2. # Restart Claude Code session 3. /labels-sync # Sync Gitea labels 4. /sprint-plan # Plan first sprint ``` +### Example 8: New Project Setup (System Already Configured) + +Adding a new project when system config exists: + +``` +1. /project-init # Quick project setup + # → Confirms detected repo name + # → Creates .env +2. /labels-sync # Sync Gitea labels +3. /sprint-plan # Plan first sprint +``` + --- ## Quick Tips @@ -188,4 +214,4 @@ Ensure credentials are configured in `~/.config/claude/gitea.env` or `~/.config/ --- -*Last Updated: 2026-01-20* +*Last Updated: 2026-01-21* diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index ee8c74f..858f17e 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -2,92 +2,331 @@ Centralized configuration documentation for all plugins and MCP servers in the Leo Claude Marketplace. -## Overview +--- + +## Quick Start + +**After installing the marketplace and plugins via Claude Code:** + +``` +/initial-setup +``` + +The interactive wizard handles everything except manually adding your API tokens. + +--- + +## Setup Flow Diagram + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ FIRST TIME SETUP │ +│ (once per machine) │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ + ▼ + /initial-setup + │ + ┌──────────────────────────────┼──────────────────────────────┐ + ▼ ▼ ▼ +┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ PHASE 1 │ │ PHASE 2 │ │ PHASE 3 │ +│ Automated │───────────▶│ Automated │───────────▶│ Interactive │ +│ │ │ │ │ │ +│ • Check │ │ • Find MCP path │ │ • Ask Gitea URL │ +│ Python │ │ • Create venv │ │ • Ask Org name │ +│ version │ │ • Install deps │ │ • Create config │ +└─────────────┘ └─────────────────┘ └─────────────────┘ + │ + ▼ + ┌───────────────────────────┐ + │ PHASE 4 │ + │ USER ACTION │ + │ │ + │ Edit config file to add │ + │ API token (for security) │ + │ │ + │ nano ~/.config/claude/ │ + │ gitea.env │ + └───────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┬──────────────────────────────┐ + ▼ ▼ ▼ +┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ PHASE 5 │ │ PHASE 6 │ │ PHASE 7 │ +│ Interactive │ │ Automated │ │ Automated │ +│ │ │ │ │ │ +│ • Confirm │ │ • Create .env │ │ • Test API │ +│ repo name │ │ • Check │ │ • Show summary │ +│ from git │ │ .gitignore │ │ • Restart note │ +└─────────────┘ └─────────────────┘ └─────────────────┘ + │ + ▼ + ┌───────────────────────────┐ + │ RESTART SESSION │ + │ │ + │ MCP tools available │ + │ after restart │ + └───────────────────────────┘ + + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ NEW PROJECT SETUP │ +│ (once per project) │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ + ┌───────────────┴───────────────┐ + ▼ ▼ + /project-init /initial-setup + (direct path) (smart detection) + │ │ + │ ┌──────────┴──────────┐ + │ ▼ ▼ + │ "Quick setup" "Full setup" + │ (skips to (re-runs + │ project config) everything) + │ │ │ + └────────────────────┴─────────────────────┘ + │ + ▼ + ┌─────────────────────┐ + │ PROJECT CONFIG │ + │ │ + │ • Detect repo from │ + │ git remote │ + │ • Confirm with user │ + │ • Create .env │ + │ • Check .gitignore │ + └─────────────────────┘ + │ + ▼ + Done! +``` + +--- + +## What Runs Automatically vs User Interaction + +### `/initial-setup` - Full Setup + +| Phase | Type | What Happens | +|-------|------|--------------| +| **1. Environment Check** | Automated | Verifies Python 3.10+ is installed | +| **2. MCP Server Setup** | Automated | Finds plugin path, creates venv, installs dependencies | +| **3. System Config Creation** | Interactive | Asks for Gitea URL and organization name | +| **4. Token Entry** | **User Action** | User manually edits config file to add API token | +| **5. Project Detection** | Interactive | Shows detected repo name, asks for confirmation | +| **6. Project Config** | Automated | Creates `.env` file, checks `.gitignore` | +| **7. Validation** | Automated | Tests API connectivity, shows summary | + +### `/project-init` - Quick Project Setup + +| Phase | Type | What Happens | +|-------|------|--------------| +| **1. Pre-flight Check** | Automated | Verifies system config exists | +| **2. Project Detection** | Interactive | Shows detected repo name, asks for confirmation | +| **3. Project Config** | Automated | Creates/updates `.env` file | +| **4. Gitignore Check** | Interactive | Asks to add `.env` to `.gitignore` if missing | + +--- + +## Three Commands for Different Scenarios + +| Command | When to Use | What It Does | +|---------|-------------|--------------| +| `/initial-setup` | First time on a machine | Full setup: MCP server + system config + project config | +| `/project-init` | Starting a new project | Quick setup: project config only (assumes system is ready) | +| `/project-sync` | After repo move/rename | Updates .env to match current git remote | + +**Typical workflow:** +1. Install plugin → run `/initial-setup` (once per machine) +2. Start new project → run `/project-init` (once per project) +3. Repository moved? → run `/project-sync` (updates config) + +**Smart features:** +- `/initial-setup` detects existing system config and offers quick project setup +- All commands validate org/repo via Gitea API before saving (auto-fills if verified) +- SessionStart hook automatically detects git remote vs .env mismatches + +--- + +## Configuration Architecture This marketplace uses a **hybrid configuration** approach: -- **System-level:** Credentials and service configuration (stored once per machine) -- **Project-level:** Repository-specific settings (stored per project) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SYSTEM-LEVEL (once per machine) │ +│ ~/.config/claude/ │ +├─────────────────────────────────────────────────────────────────┤ +│ gitea.env │ GITEA_URL, GITEA_TOKEN │ +│ netbox.env │ NETBOX_URL, NETBOX_TOKEN │ +│ git-flow.env │ GIT_WORKFLOW_STYLE, GIT_DEFAULT_BASE, etc. │ +└─────────────────────────────────────────────────────────────────┘ + │ + │ Shared across all projects + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ PROJECT-LEVEL (once per project) │ +│ /.env │ +├─────────────────────────────────────────────────────────────────┤ +│ GITEA_ORG │ Organization for this project │ +│ GITEA_REPO │ Repository name for this project │ +│ GIT_WORKFLOW_STYLE │ (optional) Override system default │ +│ PR_REVIEW_* │ (optional) PR review settings │ +└─────────────────────────────────────────────────────────────────┘ +``` **Benefits:** - Single token per service (update once, use everywhere) -- Easy multi-project setup (just add `.env` per project) -- Security (tokens never committed to git) -- Project isolation (each project has its own scope) +- Easy multi-project setup (just run `/project-init` in each project) +- Security (tokens never committed to git, never typed into AI chat) +- Project isolation (each project can override defaults) + +--- ## Prerequisites -Before configuring any plugin: +Before running `/initial-setup`: 1. **Python 3.10+** installed ```bash python3 --version # Should be 3.10.0 or higher ``` -2. **Git repository** initialized +2. **Git repository** initialized (for project setup) ```bash git status # Should show initialized repository ``` -3. **Claude Code** installed and working +3. **Claude Code** installed and working with the marketplace --- -## System-Level Configuration +## Setup Methods -Configuration files stored in `~/.config/claude/`: +### Method 1: Interactive Wizard (Recommended) + +Run the setup wizard in Claude Code: + +``` +/initial-setup +``` + +The wizard will guide you through each step interactively. + +**Note:** After first-time setup, you'll need to restart your Claude Code session for MCP tools to become available. + +### Method 2: Manual Setup + +If you prefer to set up manually or need to troubleshoot: + +#### Step 1: MCP Server Setup + +```bash +# Navigate to marketplace directory +cd /path/to/leo-claude-mktplace + +# Set up Gitea MCP server +cd mcp-servers/gitea +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +deactivate + +# (Optional) Set up NetBox MCP server +cd ../netbox +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +deactivate +``` + +#### Step 2: System Configuration ```bash mkdir -p ~/.config/claude -``` -### Gitea Configuration - -Required by: `projman`, `pr-review` - -```bash +# Gitea configuration (credentials only) cat > ~/.config/claude/gitea.env << 'EOF' -# Gitea API Configuration GITEA_URL=https://gitea.example.com -GITEA_TOKEN=your_gitea_token_here -GITEA_ORG=your_organization +GITEA_TOKEN=your_token_here EOF - -# Secure the file chmod 600 ~/.config/claude/gitea.env ``` -**Variables:** +#### Step 3: Project Configuration + +In each project root: + +```bash +cat > .env << 'EOF' +GITEA_ORG=your-organization +GITEA_REPO=your-repo-name +EOF +``` + +Add `.env` to `.gitignore` if not already there. + +### Method 3: Automation Script (CI/Scripting) + +For automated setups or CI environments: + +```bash +cd /path/to/leo-claude-mktplace +./scripts/setup.sh +``` + +This script is useful for CI/CD pipelines and bulk provisioning. + +--- + +## Configuration Reference + +### System-Level Files + +Located in `~/.config/claude/`: + +| File | Required By | Purpose | +|------|-------------|---------| +| `gitea.env` | projman, pr-review | Gitea API credentials | +| `netbox.env` | cmdb-assistant | NetBox API credentials | +| `git-flow.env` | git-flow | Default git workflow settings | + +### Gitea Configuration + +```bash +# ~/.config/claude/gitea.env +GITEA_URL=https://gitea.example.com +GITEA_TOKEN=your_gitea_token_here +``` + | Variable | Description | Example | |----------|-------------|---------| | `GITEA_URL` | Gitea base URL (no `/api/v1`) | `https://gitea.example.com` | -| `GITEA_TOKEN` | Personal access token | `glpat-xxx...` | -| `GITEA_ORG` | Organization name | `bandit` | +| `GITEA_TOKEN` | Personal access token | `abc123...` | -**Generating Gitea Token:** +**Note:** `GITEA_ORG` is configured at the project level (see below) since different projects may belong to different organizations. + +**Generating a Gitea Token:** 1. Log into Gitea → **User Icon** → **Settings** 2. **Applications** tab → **Manage Access Tokens** 3. **Generate New Token** with permissions: - `repo` (all sub-permissions) - `read:org` - `read:user` - - `write:repo` (for wiki) + - `write:repo` (for wiki access) 4. Copy token immediately (shown only once) ### NetBox Configuration -Required by: `cmdb-assistant` - ```bash -cat > ~/.config/claude/netbox.env << 'EOF' -# NetBox API Configuration +# ~/.config/claude/netbox.env NETBOX_URL=https://netbox.example.com NETBOX_TOKEN=your_netbox_token_here -EOF - -chmod 600 ~/.config/claude/netbox.env ``` -**Variables:** | Variable | Description | Example | |----------|-------------|---------| | `NETBOX_URL` | NetBox base URL | `https://netbox.example.com` | @@ -95,11 +334,8 @@ chmod 600 ~/.config/claude/netbox.env ### Git-Flow Configuration -Optional system defaults for: `git-flow` - ```bash -cat > ~/.config/claude/git-flow.env << 'EOF' -# Git-Flow Default Configuration +# ~/.config/claude/git-flow.env GIT_WORKFLOW_STYLE=feature-branch GIT_DEFAULT_BASE=development GIT_AUTO_DELETE_MERGED=true @@ -107,170 +343,110 @@ GIT_AUTO_PUSH=false GIT_PROTECTED_BRANCHES=main,master,development,staging,production GIT_COMMIT_STYLE=conventional GIT_CO_AUTHOR=true -EOF ``` +| Variable | Default | Description | +|----------|---------|-------------| +| `GIT_WORKFLOW_STYLE` | `feature-branch` | Branching strategy | +| `GIT_DEFAULT_BASE` | `development` | Default base branch | +| `GIT_AUTO_DELETE_MERGED` | `true` | Delete merged branches | +| `GIT_AUTO_PUSH` | `false` | Auto-push after commit | +| `GIT_PROTECTED_BRANCHES` | `main,master,...` | Protected branches | +| `GIT_COMMIT_STYLE` | `conventional` | Commit message style | +| `GIT_CO_AUTHOR` | `true` | Include Claude co-author | + --- ## Project-Level Configuration Create `.env` in each project root: -### Gitea Repository (projman, pr-review) - ```bash -# .env in project root +# Required for projman, pr-review +GITEA_ORG=your-organization GITEA_REPO=your-repo-name -``` -### Git-Flow (project overrides) - -```bash -# .env in project root +# Optional: Override git-flow defaults GIT_WORKFLOW_STYLE=pr-required GIT_DEFAULT_BASE=main -``` -### PR Review - -```bash -# .env in project root +# Optional: PR review settings PR_REVIEW_CONFIDENCE_THRESHOLD=0.5 PR_REVIEW_AUTO_SUBMIT=false ``` ---- - -## MCP Server Installation - -MCP servers are located at repository root: `mcp-servers/` - -### Gitea MCP Server - -```bash -cd mcp-servers/gitea - -# Create virtual environment -python3 -m venv .venv - -# Activate -source .venv/bin/activate - -# Install dependencies -pip install -r requirements.txt - -# Verify -python -c "from mcp_server import server; print('OK')" - -deactivate -``` - -### NetBox MCP Server - -```bash -cd mcp-servers/netbox - -# Create virtual environment -python3 -m venv .venv - -# Activate -source .venv/bin/activate - -# Install dependencies -pip install -r requirements.txt - -# Verify -python -c "from mcp_server import server; print('OK')" - -deactivate -``` +| Variable | Required | Description | +|----------|----------|-------------| +| `GITEA_ORG` | Yes | Gitea organization for this project | +| `GITEA_REPO` | Yes | Repository name (must match Gitea exactly) | +| `GIT_WORKFLOW_STYLE` | No | Override system default | +| `PR_REVIEW_*` | No | PR review settings | --- -## Plugin Configuration Reference +## Plugin Configuration Summary -### projman - -| Level | Variable | Default | Description | -|-------|----------|---------|-------------| -| System | `GITEA_URL` | (required) | Gitea API base URL | -| System | `GITEA_TOKEN` | (required) | API token | -| System | `GITEA_ORG` | (required) | Organization name | -| Project | `GITEA_REPO` | (required) | Repository name | - -**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`, `/test-gen` - -### pr-review - -| Level | Variable | Default | Description | -|-------|----------|---------|-------------| -| System | `GITEA_URL` | (required) | Gitea API base URL | -| System | `GITEA_TOKEN` | (required) | API token | -| Project | `GITEA_REPO` | (required) | Repository name | -| Project | `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.5` | Minimum confidence | -| Project | `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit reviews | - -**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings` - -### git-flow - -| Level | Variable | Default | Description | -|-------|----------|---------|-------------| -| System/Project | `GIT_WORKFLOW_STYLE` | `feature-branch` | Branching strategy | -| System/Project | `GIT_DEFAULT_BASE` | `development` | Default base branch | -| System/Project | `GIT_AUTO_DELETE_MERGED` | `true` | Delete merged branches | -| System/Project | `GIT_AUTO_PUSH` | `false` | Auto-push after commit | -| System/Project | `GIT_PROTECTED_BRANCHES` | `main,master,...` | Protected branches | -| System/Project | `GIT_COMMIT_STYLE` | `conventional` | Commit message style | -| System/Project | `GIT_CO_AUTHOR` | `true` | Include Claude co-author | - -**Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config` - -### clarity-assist - -No configuration required. Uses sensible defaults. - -**Commands:** `/clarify`, `/quick-clarify` - -### cmdb-assistant - -| Level | Variable | Default | Description | -|-------|----------|---------|-------------| -| System | `NETBOX_URL` | (required) | NetBox API base URL | -| System | `NETBOX_TOKEN` | (required) | API token | - -### doc-guardian - -No configuration required. Hook-based plugin. - -### code-sentinel - -No configuration required. Hook-based plugin. - -### project-hygiene - -No configuration required. Hook-based plugin. - -### claude-config-maintainer - -No configuration required. +| Plugin | System Config | Project Config | Setup Commands | +|--------|---------------|----------------|----------------| +| **projman** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` | +| **pr-review** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` | +| **git-flow** | git-flow.env (optional) | .env (optional) | None needed | +| **clarity-assist** | None | None | None needed | +| **cmdb-assistant** | netbox.env | None | `/initial-setup` | +| **doc-guardian** | None | None | None needed | +| **code-sentinel** | None | None | None needed | +| **project-hygiene** | None | None | None needed | +| **claude-config-maintainer** | None | None | None needed | --- -## Multi-Project Setup +## Multi-Project Workflow -1. **System config:** Set up once (credentials) -2. **Project config:** Create `.env` in each project root +Once system-level config is set up, adding new projects is simple: -**Example:** -```bash -# ~/projects/my-app/.env -GITEA_REPO=my-app - -# ~/projects/another-app/.env -GITEA_REPO=another-app -GIT_WORKFLOW_STYLE=trunk-based +**Option 1: Use `/project-init` (faster)** ``` +cd ~/projects/new-project +/project-init +``` + +**Option 2: Use `/initial-setup` (auto-detects)** +``` +cd ~/projects/new-project +/initial-setup +# → Detects system config exists +# → Offers "Quick project setup" option +``` + +Both approaches work. Use `/project-init` when you know the system is already configured. + +--- + +## Automatic Validation Features + +### API Validation + +When running `/initial-setup`, `/project-init`, or `/project-sync`, the commands: + +1. **Detect** organization and repository from git remote URL +2. **Validate** via Gitea API: `GET /api/v1/repos/{org}/{repo}` +3. **Auto-fill** if repository exists and is accessible (no confirmation needed) +4. **Ask for confirmation** only if validation fails (404 or permission error) + +This catches typos and permission issues before saving configuration. + +### Mismatch Detection (SessionStart Hook) + +When you start a Claude Code session, a hook automatically: + +1. Reads `GITEA_ORG` and `GITEA_REPO` from `.env` +2. Compares with current `git remote get-url origin` +3. **Warns** if mismatch detected: "Repository location mismatch. Run `/project-sync` to update." + +This helps when you: +- Move a repository to a different organization +- Rename a repository +- Clone a repo but forget to update `.env` --- @@ -279,31 +455,29 @@ GIT_WORKFLOW_STYLE=trunk-based ### Test Gitea Connection ```bash -curl -H "Authorization: token YOUR_TOKEN" \ - https://gitea.example.com/api/v1/user +source ~/.config/claude/gitea.env +curl -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user" ``` -### Test MCP Server +### Verify Project Setup -```bash -cd mcp-servers/gitea -source .venv/bin/activate -python -c "from mcp_server import server; print('OK')" +In Claude Code, after restarting your session: ``` - -### Run Plugin Setup - -```bash -# For projman -/initial-setup /labels-sync ``` +If this works, your setup is complete. + --- ## Troubleshooting -### Configuration not found +### MCP tools not available + +**Cause:** Session wasn't restarted after setup. +**Solution:** Exit Claude Code and start a new session. + +### "Configuration not found" error ```bash # Check system config exists @@ -317,23 +491,25 @@ stat ~/.config/claude/gitea.env ```bash # Test token directly -curl -H "Authorization: token YOUR_TOKEN" \ - https://gitea.example.com/api/v1/user - -# Regenerate if invalid +source ~/.config/claude/gitea.env +curl -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user" ``` -### MCP server not starting +If you get 401, regenerate your token in Gitea. + +### MCP server won't start ```bash # Check venv exists -ls mcp-servers/gitea/.venv +ls /path/to/mcp-servers/gitea/.venv # Reinstall if missing -cd mcp-servers/gitea +cd /path/to/mcp-servers/gitea +rm -rf .venv python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt +deactivate ``` ### Wrong repository @@ -342,7 +518,7 @@ pip install -r requirements.txt # Check project .env cat .env -# Verify GITEA_REPO matches exactly +# Verify GITEA_REPO matches the Gitea repository name exactly ``` --- @@ -358,23 +534,14 @@ cat .env chmod 600 ~/.config/claude/*.env ``` -3. **Rotate tokens periodically** +3. **Never type tokens into AI chat** + - Always edit config files directly in your editor + - The `/initial-setup` wizard respects this + +4. **Rotate tokens periodically** - Every 6-12 months - Immediately if compromised -4. **Minimum permissions** +5. **Minimum permissions** - Only grant required token permissions - Use separate tokens for different environments - ---- - -## Quick Setup Checklist - -- [ ] Python 3.10+ installed -- [ ] `~/.config/claude/` directory created -- [ ] Service credentials configured (gitea.env, netbox.env) -- [ ] Configuration files secured (chmod 600) -- [ ] MCP servers installed with venv -- [ ] Project `.env` created with repository settings -- [ ] Connections tested -- [ ] Plugin commands verified diff --git a/docs/UPDATING.md b/docs/UPDATING.md index 5008b81..3fa027a 100644 --- a/docs/UPDATING.md +++ b/docs/UPDATING.md @@ -2,6 +2,8 @@ This guide covers how to update your local installation when new versions are released. +--- + ## Quick Update ```bash @@ -13,12 +15,40 @@ git pull origin main ./scripts/post-update.sh ``` +**Then restart your Claude Code session** to load any changes. + +--- + ## What the Post-Update Script Does -1. **Updates Python dependencies** for MCP servers +1. **Updates Python dependencies** for MCP servers (gitea, netbox) 2. **Shows recent changelog entries** so you know what changed 3. **Validates your configuration** is still compatible +--- + +## After Updating: Re-run Setup if Needed + +### When to Re-run `/initial-setup` + +You typically **don't need** to re-run setup after updates. However, re-run if: + +- Changelog mentions **new required environment variables** +- Changelog mentions **breaking changes** to configuration +- MCP tools stop working after update + +### For Existing Projects + +If an update requires new project-level configuration: + +``` +/project-init +``` + +This will detect existing settings and only add what's missing. + +--- + ## Manual Steps After Update Some updates may require manual configuration changes: @@ -29,7 +59,7 @@ If the changelog mentions new environment variables: 1. Check the variable name and purpose in the changelog 2. Add it to the appropriate config file: - - Gitea variables → `~/.config/claude/gitea.env` + - System variables → `~/.config/claude/gitea.env` or `netbox.env` - Project variables → `.env` in your project root ### New MCP Server Features @@ -37,20 +67,56 @@ If the changelog mentions new environment variables: If a new MCP server tool is added: 1. The post-update script handles dependency installation -2. Check `plugins/projman/README.md` for usage documentation -3. New tools are available immediately after update +2. Check plugin documentation for usage +3. New tools are available immediately after session restart ### Breaking Changes Breaking changes will be clearly marked in CHANGELOG.md with migration instructions. -## Troubleshooting +### Setup Script and Configuration Workflow Changes + +When updating, review if changes affect the setup workflow: + +1. **Check for setup command changes:** + ```bash + git diff HEAD~1 plugins/*/commands/initial-setup.md + git diff HEAD~1 plugins/*/commands/project-init.md + git diff HEAD~1 plugins/*/commands/project-sync.md + ``` + +2. **Check for hook changes:** + ```bash + git diff HEAD~1 plugins/*/hooks/hooks.json + ``` + +3. **Check for configuration structure changes:** + ```bash + git diff HEAD~1 docs/CONFIGURATION.md + ``` + +**If setup commands changed:** +- Review what's new (new validation steps, new prompts, etc.) +- Consider re-running `/initial-setup` or `/project-init` to benefit from improvements +- Existing configurations remain valid unless changelog notes breaking changes + +**If hooks changed:** +- Restart your Claude Code session to load new hooks +- New hooks (like SessionStart validation) activate automatically + +**If configuration structure changed:** +- Check if new variables are required +- Run `/project-sync` if repository detection logic improved + +--- + +## Troubleshooting Updates ### Dependencies fail to install ```bash # Rebuild virtual environment -cd plugins/projman/mcp-servers/gitea +cd mcp-servers/gitea rm -rf .venv python3 -m venv .venv source .venv/bin/activate @@ -61,14 +127,23 @@ deactivate ### Configuration no longer works 1. Check CHANGELOG.md for breaking changes -2. Compare your config files with updated `.env.example` (if provided) -3. Run `./scripts/setup.sh` to validate configuration +2. Run `/initial-setup` to re-validate and fix configuration +3. Compare your config files with documentation in `docs/CONFIGURATION.md` -### MCP server won't start +### MCP server won't start after update 1. Check Python version: `python3 --version` (requires 3.10+) -2. Verify venv exists: `ls plugins/projman/mcp-servers/gitea/.venv` -3. Check logs for specific errors +2. Verify venv exists: `ls mcp-servers/gitea/.venv` +3. Restart Claude Code session +4. Check logs for specific errors + +### New commands not available + +1. Restart your Claude Code session +2. Verify the plugin is still installed +3. Check if the command requires additional setup + +--- ## Version Pinning @@ -79,15 +154,28 @@ To stay on a specific version: git tag # Checkout specific version -git checkout v2.2.0 +git checkout v3.0.0 # Run post-update ./scripts/post-update.sh ``` +--- + +## Checking Current Version + +The version is displayed in the main README.md title and in `CHANGELOG.md`. + +```bash +# Check version from changelog +head -20 CHANGELOG.md +``` + +--- + ## Getting Help -- Check `plugins/projman/README.md` for projman documentation -- Check `plugins/projman/CONFIGURATION.md` for setup guide -- Review CHANGELOG.md for recent changes +- Check `docs/CONFIGURATION.md` for setup guide +- Check `docs/COMMANDS-CHEATSHEET.md` for command reference +- Review `CHANGELOG.md` for recent changes - Search existing issues in Gitea diff --git a/plugins/cmdb-assistant/commands/initial-setup.md b/plugins/cmdb-assistant/commands/initial-setup.md new file mode 100644 index 0000000..948f10f --- /dev/null +++ b/plugins/cmdb-assistant/commands/initial-setup.md @@ -0,0 +1,160 @@ +--- +description: Interactive setup wizard for cmdb-assistant plugin - configures NetBox MCP server +--- + +# CMDB Assistant Setup Wizard + +This command sets up the cmdb-assistant plugin with NetBox integration. + +## Important Context + +- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools +- **MCP tools won't work until after setup + session restart** +- **Uses NetBox MCP server (separate from Gitea MCP)** + +--- + +## Phase 1: Environment Validation + +### Step 1.1: Check Python Version + +```bash +python3 --version +``` + +If below 3.10, stop setup and inform user. + +--- + +## Phase 2: MCP Server Setup + +### Step 2.1: Locate NetBox MCP Server + +```bash +find ~/.claude ~/.config/claude -name "mcp_server" -path "*netbox*" 2>/dev/null | head -5 +``` + +If not found, ask user for marketplace location. + +### Step 2.2: Check Virtual Environment + +```bash +ls -la /path/to/mcp-servers/netbox/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING" +``` + +### Step 2.3: Create Virtual Environment (if missing) + +```bash +cd /path/to/mcp-servers/netbox && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate +``` + +--- + +## Phase 3: System Configuration + +### Step 3.1: Create Config Directory + +```bash +mkdir -p ~/.config/claude +``` + +### Step 3.2: Check NetBox Configuration + +```bash +cat ~/.config/claude/netbox.env 2>/dev/null || echo "FILE_NOT_FOUND" +``` + +**If file exists with valid values:** Skip to Phase 4. +**If missing or has placeholders:** Continue. + +### Step 3.3: Gather NetBox Information + +Use AskUserQuestion: +- Question: "What is your NetBox server URL? (e.g., https://netbox.company.com)" +- Header: "NetBox URL" +- Options: + - "Other (I'll provide the URL)" + +Ask user to provide the URL. + +### Step 3.4: Create Configuration File + +```bash +cat > ~/.config/claude/netbox.env << 'EOF' +# NetBox API Configuration +# Generated by cmdb-assistant /initial-setup + +NETBOX_URL= +NETBOX_TOKEN=PASTE_YOUR_TOKEN_HERE +EOF +chmod 600 ~/.config/claude/netbox.env +``` + +### Step 3.5: Token Instructions + +--- + +**Action Required: Add Your NetBox API Token** + +I've created `~/.config/claude/netbox.env` but you need to add your API token manually. + +**Steps:** +1. Open: `nano ~/.config/claude/netbox.env` +2. Generate token in NetBox: Admin → API Tokens → Add Token +3. Replace `PASTE_YOUR_TOKEN_HERE` with your token +4. Save the file + +--- + +Use AskUserQuestion: +- Question: "Have you added your NetBox token?" +- Header: "Token" +- Options: + - "Yes, I've added the token" + - "Skip for now" + +--- + +## Phase 4: Validation + +### Step 4.1: Test Configuration (if token was added) + +```bash +source ~/.config/claude/netbox.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Token $NETBOX_TOKEN" "$NETBOX_URL/api/" +``` + +Report result: +- 200: Success +- 403: Invalid token +- Other: Connection issue + +### Step 4.2: Summary + +``` +╔════════════════════════════════════════════════════════════╗ +║ CMDB-ASSISTANT SETUP COMPLETE ║ +╠════════════════════════════════════════════════════════════╣ +║ MCP Server (NetBox): ✓ Ready ║ +║ System Config: ✓ ~/.config/claude/netbox.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 `/cmdb-device ` to look up a device +- Run `/cmdb-ip
` to look up an IP address +- Run `/cmdb-site ` to look up a site +- Run `/cmdb-search ` for general search + +--- + +## Note on Project Configuration + +cmdb-assistant does not require project-level configuration. The NetBox connection is system-wide and not tied to specific repositories. diff --git a/plugins/pr-review/commands/initial-setup.md b/plugins/pr-review/commands/initial-setup.md new file mode 100644 index 0000000..476ce3d --- /dev/null +++ b/plugins/pr-review/commands/initial-setup.md @@ -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= +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//" +``` + +| HTTP Code | Action | +|-----------|--------| +| **200** | Auto-fill - "Verified: / 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 '' 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 '' 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=" >> .env +echo "GITEA_REPO=" >> .env +``` + +If `.env` doesn't exist: +```bash +cat > .env << 'EOF' +# Project Configuration +GITEA_ORG= +GITEA_REPO= +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 ` to review a pull request +- Run `/pr-summary ` for a quick summary +- Run `/pr-findings ` to list actionable findings + +--- + +## Available Commands After Setup + +| Command | Description | +|---------|-------------| +| `/pr-review ` | Full multi-agent PR review with confidence scoring | +| `/pr-summary ` | Quick PR summary | +| `/pr-findings ` | List findings with severity and line numbers | diff --git a/plugins/pr-review/commands/project-init.md b/plugins/pr-review/commands/project-init.md new file mode 100644 index 0000000..a7492a9 --- /dev/null +++ b/plugins/pr-review/commands/project-init.md @@ -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//" +``` + +| HTTP Code | Action | +|-----------|--------| +| **200** | Auto-fill - "Verified: / 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 '' 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 '' 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=" >> .env +echo "GITEA_REPO=" >> .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: ║ +║ Repository: ║ +║ Config file: ./.env ║ +╚══════════════════════════════════════════════════════════════╝ + +Ready to review PRs: +• /pr-review - Full multi-agent review +• /pr-summary - Quick summary +• /pr-findings - List findings +``` diff --git a/plugins/pr-review/commands/project-sync.md b/plugins/pr-review/commands/project-sync.md new file mode 100644 index 0000000..d5b7838 --- /dev/null +++ b/plugins/pr-review/commands/project-sync.md @@ -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//" +``` + +| 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=/' .env +sed -i 's/^GITEA_REPO=.*/GITEA_REPO=/' .env +``` + +--- + +## Step 7: Confirm Success + +``` +╔══════════════════════════════════════════════════════════════╗ +║ CONFIGURATION UPDATED ║ +╠══════════════════════════════════════════════════════════════╣ +║ Organization: ║ +║ Repository: ║ +╚══════════════════════════════════════════════════════════════╝ +``` diff --git a/plugins/pr-review/hooks/hooks.json b/plugins/pr-review/hooks/hooks.json new file mode 100644 index 0000000..d6bde9d --- /dev/null +++ b/plugins/pr-review/hooks/hooks.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": ".*", + "hooks": [ + { + "type": "prompt", + "prompt": "Silently check if the project's git remote matches the .env configuration:\n\n1. Read .env to get GITEA_ORG and GITEA_REPO values\n2. Run: git remote get-url origin\n3. Extract org and repo from the remote URL\n4. Compare with .env values\n\nIf mismatch detected:\n- Display a brief warning: 'Repository location mismatch detected. Git remote shows / but .env has /. Run /project-sync to update.'\n\nIf match or no .env exists: Stay silent, do not interrupt.\n\nThis check should be quick and non-blocking." + } + ] + } + ] + } +} diff --git a/plugins/projman/CONFIGURATION.md b/plugins/projman/CONFIGURATION.md index 349f1a0..476cd04 100644 --- a/plugins/projman/CONFIGURATION.md +++ b/plugins/projman/CONFIGURATION.md @@ -1,39 +1,10 @@ -# Configuration Guide - Projman Plugin +# Configuration - Projman Plugin -For comprehensive configuration instructions, see the **[Centralized Configuration Guide](../../docs/CONFIGURATION.md)**. +See **[docs/CONFIGURATION.md](../../docs/CONFIGURATION.md)** for complete setup instructions. -## Quick Reference +## Quick Commands -### Required Configuration - -**System-level** (`~/.config/claude/gitea.env`): -```bash -GITEA_URL=https://gitea.example.com -GITEA_TOKEN=your_token -GITEA_ORG=your_organization ``` - -**Project-level** (`.env` in project root): -```bash -GITEA_REPO=your-repo-name +/initial-setup # First time on this machine +/project-init # New project (system already configured) ``` - -### MCP Server Installation - -```bash -cd mcp-servers/gitea -python3 -m venv .venv -source .venv/bin/activate -pip install -r requirements.txt -``` - -### Verification - -```bash -/initial-setup -/labels-sync -``` - ---- - -For detailed setup instructions, troubleshooting, and security best practices, see [docs/CONFIGURATION.md](../../docs/CONFIGURATION.md). diff --git a/plugins/projman/README.md b/plugins/projman/README.md index 5f7df7c..8ff524f 100644 --- a/plugins/projman/README.md +++ b/plugins/projman/README.md @@ -25,57 +25,38 @@ Projman transforms a proven 15-sprint workflow into a distributable Claude Code - Python 3.10+ installed - Git repository initialized -### 2. Install MCP Server +### 2. Run Interactive Setup -The plugin bundles the Gitea MCP server: +The setup wizard handles everything: -```bash -cd plugins/projman/mcp-servers/gitea -python3 -m venv .venv -source .venv/bin/activate # or .venv\Scripts\activate on Windows -pip install -r requirements.txt ``` - -See [CONFIGURATION.md](./CONFIGURATION.md) for detailed setup instructions. - -### 3. Configure System-Level Settings - -Create system-wide configuration with your Gitea credentials: - -```bash -mkdir -p ~/.config/claude - -# Gitea configuration -cat > ~/.config/claude/gitea.env << 'EOF' -GITEA_URL=https://gitea.example.com -GITEA_TOKEN=your_gitea_token_here -GITEA_ORG=your_organization -EOF - -# Secure the file -chmod 600 ~/.config/claude/gitea.env -``` - -### 4. Configure Project-Level Settings - -In your project root directory, create a `.env` file: - -```bash -# In your project directory -cat > .env << 'EOF' -GITEA_REPO=your-repo-name -EOF -``` - -### 5. Run Initial Setup - -```bash /initial-setup ``` -### 6. Start Planning! +This will: +- Set up the MCP server (Python venv + dependencies) +- Create system config (`~/.config/claude/gitea.env`) +- Guide you through adding your Gitea token +- Detect and validate your repository via API +- Create project config (`.env`) -```bash +**For new projects** (when system is already configured): + +``` +/project-init +``` + +**After moving a repository:** + +``` +/project-sync +``` + +See [docs/CONFIGURATION.md](../../docs/CONFIGURATION.md) for detailed instructions. + +### 3. Start Planning! + +``` /sprint-plan ``` @@ -164,15 +145,40 @@ Synchronize label taxonomy from Gitea. - When new labels are added to Gitea ### `/initial-setup` -Run initial setup for a new project. +Full interactive setup wizard. **What it does:** -- Validates Gitea MCP server connection -- Tests credential configuration -- Syncs label taxonomy -- Creates required directory structure +- Checks Python version (requires 3.10+) +- Sets up MCP server virtual environment +- Creates system-level config (`~/.config/claude/gitea.env`) +- Guides token setup (manual entry for security) +- Detects and validates repository via Gitea API +- Creates project-level config (`.env` with GITEA_ORG, GITEA_REPO) -**When to use:** First time setting up projman for a project +**When to use:** First time on a new machine + +### `/project-init` +Quick project setup (assumes system config exists). + +**What it does:** +- Verifies system configuration exists +- Detects organization and repository from git remote +- Validates via Gitea API +- Creates project `.env` file + +**When to use:** Starting work on a new project + +### `/project-sync` +Sync configuration with current git remote. + +**What it does:** +- Compares .env values with git remote URL +- Validates new repository via Gitea API +- Updates .env if mismatch detected + +**When to use:** After moving or renaming a repository + +**Note:** A SessionStart hook automatically detects mismatches and warns you to run `/project-sync`. ### `/review` Pre-sprint-close code quality review. diff --git a/plugins/projman/commands/initial-setup.md b/plugins/projman/commands/initial-setup.md index e9140d3..8875a1c 100644 --- a/plugins/projman/commands/initial-setup.md +++ b/plugins/projman/commands/initial-setup.md @@ -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= +GITEA_TOKEN=PASTE_YOUR_TOKEN_HERE +EOF +chmod 600 ~/.config/claude/gitea.env +``` + +Replace `` 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//" +``` + +**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 '/' exists and is accessible." + +### Step 4.5: Confirm Organization (only if API validation failed) + +Use AskUserQuestion: +- Question: "Repository '/' was not found. Is '' 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 '' 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= +GITEA_REPO= +EOF +``` + +Replace `` 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 | +| `/.venv/` | Python environment | Dependencies | diff --git a/plugins/projman/commands/project-init.md b/plugins/projman/commands/project-init.md new file mode 100644 index 0000000..dda79bd --- /dev/null +++ b/plugins/projman/commands/project-init.md @@ -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//" +``` + +| HTTP Code | Action | +|-----------|--------| +| **200** | Auto-fill - display "Verified: / 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 '' 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 '' 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=" >> .env +echo "GITEA_REPO=" >> .env +``` + +**If `.env` doesn't exist:** + +```bash +cat > .env << 'EOF' +# Project Configuration for projman +# Generated by /project-init + +GITEA_ORG= +GITEA_REPO= +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: ║ +║ Repository: ║ +║ 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" diff --git a/plugins/projman/commands/project-sync.md b/plugins/projman/commands/project-sync.md new file mode 100644 index 0000000..7f8e180 --- /dev/null +++ b/plugins/projman/commands/project-sync.md @@ -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: ║ +║ Repository: ║ +║ 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: │ ║ +║ Repository: │ ║ +╚══════════════════════════════════════════════════════════════╝ +``` + +--- + +## 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//" +``` + +| 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 '/' 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=/' .env + +# Update GITEA_REPO +sed -i 's/^GITEA_REPO=.*/GITEA_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: ║ +║ Repository: ║ +║ 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 ` +- Then run `/project-sync` again + +**Want to revert the change:** +- Edit `.env` manually: `nano .env` +- Or run `/project-sync` after fixing the git remote diff --git a/plugins/projman/hooks/hooks.json b/plugins/projman/hooks/hooks.json new file mode 100644 index 0000000..d6bde9d --- /dev/null +++ b/plugins/projman/hooks/hooks.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": ".*", + "hooks": [ + { + "type": "prompt", + "prompt": "Silently check if the project's git remote matches the .env configuration:\n\n1. Read .env to get GITEA_ORG and GITEA_REPO values\n2. Run: git remote get-url origin\n3. Extract org and repo from the remote URL\n4. Compare with .env values\n\nIf mismatch detected:\n- Display a brief warning: 'Repository location mismatch detected. Git remote shows / but .env has /. Run /project-sync to update.'\n\nIf match or no .env exists: Stay silent, do not interrupt.\n\nThis check should be quick and non-blocking." + } + ] + } + ] + } +} diff --git a/scripts/setup.sh b/scripts/setup.sh index 0d4ec51..d2c3078 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -1,6 +1,17 @@ #!/usr/bin/env bash # -# setup.sh - Initial setup for Leo Claude Marketplace +# setup.sh - Automated setup for Leo Claude Marketplace +# +# ============================================================================ +# NOTE: For interactive setup, use the /initial-setup command in Claude Code +# instead of this script. The command provides a guided wizard experience. +# +# This script is intended for: +# - CI/CD pipelines +# - Automated deployments +# - Bulk machine provisioning +# - Fallback when Claude Code is not available +# ============================================================================ # # Usage: ./scripts/setup.sh #