diff --git a/CLAUDE.md b/CLAUDE.md index 30779ea..0bd4a48 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,19 +28,23 @@ A plugin marketplace for Claude Code containing: # Validate marketplace compliance ./scripts/validate-marketplace.sh -# 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 -/test-check # Verify tests before close -/sprint-close # Complete sprint +# After updates +./scripts/post-update.sh # Rebuild venvs, verify symlinks ``` +### Plugin Commands by Category + +| Category | Commands | +|----------|----------| +| **Setup** | `/initial-setup`, `/project-init`, `/project-sync` | +| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close` | +| **Quality** | `/review`, `/test-check`, `/test-gen` | +| **PR Review** | `/pr-review:initial-setup`, `/pr-review:project-init` | +| **Docs** | `/doc-audit`, `/doc-sync` | +| **Security** | `/security-scan`, `/refactor`, `/refactor-dry` | +| **Config** | `/config-analyze`, `/config-optimize` | +| **Debug** | `/debug-report`, `/debug-review` | + ## Repository Structure ``` @@ -208,42 +212,47 @@ Stored in Gitea Wiki under `lessons-learned/sprints/`. | Document | Purpose | |----------|---------| | `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths | -| `docs/COMMANDS-CHEATSHEET.md` | All commands quick reference with workflow examples | +| `docs/COMMANDS-CHEATSHEET.md` | All commands quick reference | | `docs/CONFIGURATION.md` | Centralized setup guide | +| `docs/DEBUGGING-CHECKLIST.md` | Systematic troubleshooting guide | | `docs/UPDATING.md` | Update guide for the marketplace | -| `plugins/projman/CONFIGURATION.md` | Quick reference (links to central) | +| `plugins/projman/CONFIGURATION.md` | Projman quick reference (links to central) | | `plugins/projman/README.md` | Projman full documentation | -## Versioning and Changelog Rules +## Installation Paths -### Version Display -**The marketplace version is displayed ONLY in the main `README.md` title.** +Understanding where files live is critical for debugging: -- Format: `# Leo Claude Marketplace - vX.Y.Z` -- Do NOT add version numbers to individual plugin documentation titles -- Do NOT add version numbers to configuration guides -- Do NOT add version numbers to CLAUDE.md or other docs +| Context | Path | Purpose | +|---------|------|---------| +| **Source** | `~/claude-plugins-work/` | Development - edit here | +| **Installed** | `~/.claude/plugins/marketplaces/leo-claude-mktplace/` | Runtime - Claude uses this | +| **Cache** | `~/.claude/` | Plugin metadata and settings | -### Changelog Maintenance (MANDATORY) -**`CHANGELOG.md` is the authoritative source for version history.** +**Key insight:** Edits to source require reinstall/update to take effect at runtime. -When releasing a new version: -1. Update main `README.md` title with new version -2. Update `CHANGELOG.md` with: - - Version number and date: `## [X.Y.Z] - YYYY-MM-DD` - - **Added**: New features, commands, files - - **Changed**: Modifications to existing functionality - - **Fixed**: Bug fixes - - **Removed**: Deleted features, files, deprecated items -3. Update `marketplace.json` metadata version -4. Update plugin `plugin.json` versions if plugin-specific changes +## Debugging & Troubleshooting -### Version Format -- Follow [Semantic Versioning](https://semver.org/): MAJOR.MINOR.PATCH -- MAJOR: Breaking changes -- MINOR: New features, backward compatible -- PATCH: Bug fixes, minor improvements +See `docs/DEBUGGING-CHECKLIST.md` for systematic troubleshooting. + +**Common Issues:** +| Symptom | Likely Cause | Fix | +|---------|--------------|-----| +| "X MCP servers failed" | Missing venv in installed path | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` | +| MCP tools not available | Symlink broken or venv missing | Run `/debug-report` to diagnose | +| Changes not taking effect | Editing source, not installed | Reinstall plugin or edit installed path | + +**Debug Commands:** +- `/debug-report` - Run full diagnostics, create issue if needed +- `/debug-review` - Investigate and propose fixes + +## Versioning Rules + +- Version displayed ONLY in main `README.md` title: `# Leo Claude Marketplace - vX.Y.Z` +- `CHANGELOG.md` is authoritative for version history +- Follow [SemVer](https://semver.org/): MAJOR.MINOR.PATCH +- On release: Update README title → CHANGELOG → marketplace.json → plugin.json files --- -**Last Updated:** 2026-01-20 +**Last Updated:** 2026-01-22 diff --git a/docs/CANONICAL-PATHS.md b/docs/CANONICAL-PATHS.md index 647e677..b97e87a 100644 --- a/docs/CANONICAL-PATHS.md +++ b/docs/CANONICAL-PATHS.md @@ -18,6 +18,7 @@ leo-claude-mktplace/ │ ├── architecture/ # Draw.io diagrams and specs │ ├── CANONICAL-PATHS.md # This file - single source of truth │ ├── CONFIGURATION.md # Centralized configuration guide +│ ├── DEBUGGING-CHECKLIST.md # Systematic troubleshooting guide │ ├── UPDATING.md # Update guide │ └── workflows/ # Workflow documentation ├── hooks/ # Shared hooks (if any) @@ -103,6 +104,10 @@ leo-claude-mktplace/ │ ├── skills/ │ └── claude-md-integration.md ├── scripts/ # Setup and maintenance scripts +│ ├── setup.sh # Initial setup (create venvs, config templates) +│ ├── post-update.sh # Post-update (rebuild venvs, verify symlinks) +│ ├── check-venv.sh # Check if venvs exist (for hooks) +│ └── validate-marketplace.sh # Marketplace compliance validation ├── CLAUDE.md ├── README.md ├── LICENSE @@ -156,6 +161,7 @@ The symlink target is relative: `../../../mcp-servers/{server}` | Update guide | `docs/UPDATING.md` | | Configuration guide | `docs/CONFIGURATION.md` | | Commands cheat sheet | `docs/COMMANDS-CHEATSHEET.md` | +| Debugging checklist | `docs/DEBUGGING-CHECKLIST.md` | --- diff --git a/docs/DEBUGGING-CHECKLIST.md b/docs/DEBUGGING-CHECKLIST.md new file mode 100644 index 0000000..e0a442a --- /dev/null +++ b/docs/DEBUGGING-CHECKLIST.md @@ -0,0 +1,213 @@ +# Debugging Checklist for Marketplace Troubleshooting + +**Purpose:** Systematic approach to diagnose and fix plugin loading issues. + +Last Updated: 2026-01-22 + +--- + +## Step 1: Identify the Loading Path + +Claude Code loads plugins from different locations depending on context: + +| Location | Path | When Used | +|----------|------|-----------| +| **Source** | `~/claude-plugins-work/` | When developing in this directory | +| **Installed** | `~/.claude/plugins/marketplaces/leo-claude-mktplace/` | After marketplace install | +| **Cache** | `~/.claude/` | Plugin metadata, settings | + +**Determine which path Claude is using:** + +```bash +# Check if installed marketplace exists +ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/ + +# Check Claude's current plugin loading +cat ~/.claude/settings.local.json | grep -A5 "mcpServers" +``` + +**Key insight:** If you're editing source but Claude uses installed, your changes won't take effect. + +--- + +## Step 2: Verify Files Exist at Runtime Location + +Check the files Claude will actually load: + +```bash +# For installed marketplace +RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace + +# Check MCP server exists +ls -la $RUNTIME/mcp-servers/gitea/ +ls -la $RUNTIME/mcp-servers/netbox/ + +# Check plugin manifests +ls -la $RUNTIME/plugins/projman/.claude-plugin/plugin.json +ls -la $RUNTIME/plugins/pr-review/.claude-plugin/plugin.json + +# Check .mcp.json files +cat $RUNTIME/plugins/projman/.mcp.json +``` + +--- + +## Step 3: Verify Virtual Environments Exist + +**This is the most common failure point after installation.** + +MCP servers require Python venvs to exist at the INSTALLED location: + +```bash +RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace + +# Check venvs exist +ls -la $RUNTIME/mcp-servers/gitea/.venv/bin/python +ls -la $RUNTIME/mcp-servers/netbox/.venv/bin/python + +# If missing, create them: +cd $RUNTIME && ./scripts/setup.sh +``` + +**Common error:** "X MCP servers failed to start" = venvs don't exist in installed path. + +--- + +## Step 4: Verify Symlink Resolution + +Plugins use symlinks to shared MCP servers. Verify they resolve correctly: + +```bash +RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace + +# Check symlinks exist and resolve +readlink -f $RUNTIME/plugins/projman/mcp-servers/gitea +readlink -f $RUNTIME/plugins/pr-review/mcp-servers/gitea +readlink -f $RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox + +# Should resolve to: +# $RUNTIME/mcp-servers/gitea +# $RUNTIME/mcp-servers/netbox +``` + +**If broken:** Symlinks are relative. If directory structure differs, they'll break. + +--- + +## Step 5: Test MCP Server Startup + +Manually test if the MCP server can start: + +```bash +RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace + +# Test Gitea MCP +cd $RUNTIME/mcp-servers/gitea +PYTHONPATH=. .venv/bin/python -c "from mcp_server.server import main; print('OK')" + +# Test NetBox MCP +cd $RUNTIME/mcp-servers/netbox +PYTHONPATH=. .venv/bin/python -c "from mcp_server.server import main; print('OK')" +``` + +**If import fails:** Check requirements.txt installed, check Python version compatibility. + +--- + +## Step 6: Verify Configuration Files + +Check environment variables are set: + +```bash +# System-level credentials (should exist) +cat ~/.config/claude/gitea.env +# Should contain: GITEA_API_URL, GITEA_API_TOKEN + +cat ~/.config/claude/netbox.env +# Should contain: NETBOX_API_URL, NETBOX_API_TOKEN + +# Project-level config (in target project) +cat /path/to/project/.env +# Should contain: GITEA_ORG, GITEA_REPO +``` + +--- + +## Step 7: Verify Hooks Configuration + +Check hooks are valid: + +```bash +RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace + +# List all hooks.json files +find $RUNTIME/plugins -name "hooks.json" -exec echo "=== {} ===" \; -exec cat {} \; + +# Verify hook events are valid +# Valid: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, +# Notification, Stop, SubagentStop, PreCompact +# INVALID: task-completed, file-changed, git-commit-msg-needed +``` + +--- + +## Quick Diagnostic Commands + +Run these to quickly identify issues: + +```bash +RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace + +echo "=== Installation Status ===" +[ -d "$RUNTIME" ] && echo "Installed: YES" || echo "Installed: NO" + +echo -e "\n=== Virtual Environments ===" +[ -f "$RUNTIME/mcp-servers/gitea/.venv/bin/python" ] && echo "Gitea venv: OK" || echo "Gitea venv: MISSING" +[ -f "$RUNTIME/mcp-servers/netbox/.venv/bin/python" ] && echo "NetBox venv: OK" || echo "NetBox venv: MISSING" + +echo -e "\n=== Symlinks ===" +[ -L "$RUNTIME/plugins/projman/mcp-servers/gitea" ] && echo "projman->gitea: OK" || echo "projman->gitea: MISSING" +[ -L "$RUNTIME/plugins/pr-review/mcp-servers/gitea" ] && echo "pr-review->gitea: OK" || echo "pr-review->gitea: MISSING" +[ -L "$RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox" ] && echo "cmdb-assistant->netbox: OK" || echo "cmdb-assistant->netbox: MISSING" + +echo -e "\n=== Config Files ===" +[ -f ~/.config/claude/gitea.env ] && echo "gitea.env: OK" || echo "gitea.env: MISSING" +[ -f ~/.config/claude/netbox.env ] && echo "netbox.env: OK" || echo "netbox.env: MISSING" +``` + +--- + +## Common Issues and Fixes + +| Issue | Symptom | Fix | +|-------|---------|-----| +| Missing venvs | "X MCP servers failed" | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` | +| Broken symlinks | MCP tools not available | Reinstall marketplace or manually recreate symlinks | +| Wrong path edits | Changes don't take effect | Edit installed path or reinstall after source changes | +| Missing credentials | MCP connection errors | Create `~/.config/claude/gitea.env` with API credentials | +| Invalid hook events | Hooks don't fire | Use only valid event names (see Step 7) | + +--- + +## After Fixing Issues + +1. **Restart Claude Code** - Plugins are loaded at startup +2. **Verify fix works** - Run a simple command that uses the MCP +3. **Document the issue** - If it's a new failure mode, add to this checklist + +--- + +## Automated Diagnostics + +Use these commands for automated checking: + +- `/debug-report` - Run full diagnostics, create issue if problems found +- `/debug-review` - Investigate existing diagnostic issues and propose fixes + +--- + +## Related Documentation + +- `CLAUDE.md` - Installation Paths and Troubleshooting sections +- `docs/CONFIGURATION.md` - Setup and configuration guide +- `docs/UPDATING.md` - Update procedures diff --git a/plugins/pr-review/hooks/hooks.json b/plugins/pr-review/hooks/hooks.json index 45245d4..c19701b 100644 --- a/plugins/pr-review/hooks/hooks.json +++ b/plugins/pr-review/hooks/hooks.json @@ -3,7 +3,7 @@ "SessionStart": [ { "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." + "prompt": "Perform silent startup checks:\n\n1. Check if MCP venvs exist at the installed marketplace location. If the marketplace is installed but venvs are missing, warn the user to run setup.sh from that location.\n\n2. Check if the project git remote matches .env configuration (GITEA_ORG/GITEA_REPO). If mismatch, warn about /project-sync.\n\nStay silent if all checks pass or not applicable. Be quick and non-blocking." } ] } diff --git a/plugins/projman/README.md b/plugins/projman/README.md index e9d63e0..ccaaa76 100644 --- a/plugins/projman/README.md +++ b/plugins/projman/README.md @@ -178,7 +178,9 @@ Sync configuration with current git remote. **When to use:** After moving or renaming a repository -**Note:** A SessionStart hook automatically detects mismatches and warns you to run `/project-sync`. +**Note:** A SessionStart hook automatically checks for: +1. Missing MCP venvs at the installed marketplace location (warns to run setup.sh) +2. Repository config mismatches (warns to run `/project-sync`) ### `/review` Pre-sprint-close code quality review. diff --git a/plugins/projman/hooks/hooks.json b/plugins/projman/hooks/hooks.json index 45245d4..c19701b 100644 --- a/plugins/projman/hooks/hooks.json +++ b/plugins/projman/hooks/hooks.json @@ -3,7 +3,7 @@ "SessionStart": [ { "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." + "prompt": "Perform silent startup checks:\n\n1. Check if MCP venvs exist at the installed marketplace location. If the marketplace is installed but venvs are missing, warn the user to run setup.sh from that location.\n\n2. Check if the project git remote matches .env configuration (GITEA_ORG/GITEA_REPO). If mismatch, warn about /project-sync.\n\nStay silent if all checks pass or not applicable. Be quick and non-blocking." } ] } diff --git a/scripts/check-venv.sh b/scripts/check-venv.sh new file mode 100755 index 0000000..81c4b16 --- /dev/null +++ b/scripts/check-venv.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# +# check-venv.sh - Check if MCP server venvs exist in installed marketplace +# +# Usage: ./scripts/check-venv.sh +# +# Exit codes: +# 0 - All venvs exist (or not installed via marketplace) +# 1 - Venvs missing, needs setup +# +# This script is designed to be called from SessionStart hooks +# to enable self-healing MCP server setup. + +set -euo pipefail + +# Installed marketplace location +MKTPLACE="$HOME/.claude/plugins/marketplaces/leo-claude-mktplace" + +# If not installed via marketplace, exit silently +if [[ ! -d "$MKTPLACE" ]]; then + exit 0 +fi + +# Check if gitea venv exists +if [[ ! -f "$MKTPLACE/mcp-servers/gitea/.venv/bin/python" ]]; then + echo "SETUP_NEEDED" + exit 1 +fi + +# Check if netbox venv exists +if [[ ! -f "$MKTPLACE/mcp-servers/netbox/.venv/bin/python" ]]; then + echo "SETUP_NEEDED" + exit 1 +fi + +# All good +exit 0