personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(hooks): remove all venv auto-repair code that deleted .venv directories #327

Merged
lmiranda merged 1 commits from fix/remove-venv-auto-repair into development 2026-01-30 16:34:59 +00:00
Conversation 0 Commits 1 Files Changed 11 +241 -228
11 changed files with 241 additions and 228 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
CLAUDE.md
View File

@@ -40,8 +40,76 @@ Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform
**Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
### ⛔ MANDATORY: Before Any Code Change
**Claude MUST show this checklist BEFORE editing any file:**
#### 1. Impact Search Results
Run and show output of:
```bash
grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
```
#### 2. Files That Will Be Affected
Numbered list of every file to be modified, with the specific change for each.
#### 3. Files Searched But Not Changed (and why)
Proof that related files were checked and determined unchanged.
#### 4. Documentation That References This
List of docs that mention this feature/script/function.
**User verifies this list before Claude proceeds. If Claude skips this, STOP IMMEDIATELY.**
#### After Changes
Run the same grep and show results proving no references remain unaddressed.
---
## ⚠️ Development Context: We Build AND Use These Plugins
**This is a self-referential project.** We are:
1. **BUILDING** a plugin marketplace (source code in `plugins/`)
2. **USING** the installed marketplace to build it (dogfooding)
### Plugins ACTIVELY USED in This Project
These plugins are installed and should be used during development:
| Plugin | Used For |
|--------|----------|
| **projman** | Sprint planning, issue management, lessons learned |
| **git-flow** | Commits, branch management |
| **pr-review** | Pull request reviews |
| **doc-guardian** | Documentation drift detection |
| **code-sentinel** | Security scanning, refactoring |
| **clarity-assist** | Prompt clarification |
| **claude-config-maintainer** | CLAUDE.md optimization |
| **contract-validator** | Cross-plugin compatibility |
### Plugins NOT Used Here (Development Only)
These plugins exist in source but are **NOT relevant** to this project's workflow:
| Plugin | Why Not Used |
|--------|--------------|
| **data-platform** | For data engineering projects (pandas, PostgreSQL, dbt) |
| **viz-platform** | For dashboard projects (Dash, Plotly) |
| **cmdb-assistant** | For infrastructure projects (NetBox) |
**Do NOT suggest** `/ingest`, `/profile`, `/chart`, `/cmdb-*` commands - they don't apply here.
### Key Distinction
| Context | Path | What To Do |
|---------|------|------------|
| **Editing plugin source** | `~/claude-plugins-work/plugins/` | Modify code, add features |
| **Using installed plugins** | `~/.claude/plugins/marketplaces/` | Run commands like `/sprint-plan` |
When user says "run /sprint-plan", use the INSTALLED plugin.
When user says "fix the sprint-plan command", edit the SOURCE code.
---
## Project Overview
@@ -76,7 +144,7 @@ A plugin marketplace for Claude Code containing:
./scripts/post-update.sh # Rebuild venvs, verify symlinks
```
### Plugin Commands by Category
### Plugin Commands - USE THESE in This Project
| Category | Commands |
|----------|----------|
@@ -88,12 +156,19 @@ A plugin marketplace for Claude Code containing:
| **Docs** | `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs` |
| **Security** | `/security-scan`, `/refactor`, `/refactor-dry` |
| **Config** | `/config-analyze`, `/config-optimize`, `/config-diff`, `/config-lint` |
| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality` |
| **Visualization** | `/component`, `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/accessibility-check`, `/breakpoints` |
| **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph` |
| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`, `/cmdb-audit`, `/cmdb-register`, `/cmdb-sync`, `/cmdb-topology`, `/change-audit`, `/ip-conflicts` |
| **Debug** | `/debug-report`, `/debug-review` |
### Plugin Commands - NOT RELEVANT to This Project
These commands are being developed but don't apply to this project's workflow:
| Category | Commands | For Projects Using |
|----------|----------|-------------------|
| **Data** | `/ingest`, `/profile`, `/schema`, `/lineage`, `/dbt-test` | pandas, PostgreSQL, dbt |
| **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme` | Dash, Plotly dashboards |
| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-sync` | NetBox infrastructure |
## Repository Structure
```
@@ -354,4 +429,4 @@ The script will:
---
**Last Updated:** 2026-01-28
**Last Updated:** 2026-01-30

7
docs/CANONICAL-PATHS.md
View File

@@ -163,12 +163,11 @@ leo-claude-mktplace/
│ └── 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)
│ ├── post-update.sh # Post-update (clear cache, show changelog)
│ ├── check-venv.sh # Check if venvs exist (read-only)
│ ├── validate-marketplace.sh # Marketplace compliance validation
│ ├── verify-hooks.sh # Verify all hooks use correct event types
│ ├── setup-venvs.sh # Setup/repair MCP server venvs
│ ├── venv-repair.sh # Repair broken venv symlinks
│ ├── setup-venvs.sh # Setup MCP server venvs (create only, never delete)
│ └── release.sh # Release automation with version bumping
├── CLAUDE.md
├── README.md

3
docs/CONFIGURATION.md
View File

@@ -501,9 +501,8 @@ If you get 401, regenerate your token in Gitea.
# Check venv exists
ls /path/to/mcp-servers/gitea/.venv
# Reinstall if missing
# If missing, create venv (do NOT delete existing venvs)
cd /path/to/mcp-servers/gitea
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

4
docs/UPDATING.md
View File

@@ -132,10 +132,8 @@ When updating, review if changes affect the setup workflow:
### Dependencies fail to install
```bash
# Rebuild virtual environment
# Install missing dependencies (do NOT delete .venv)
cd mcp-servers/gitea
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate

33
plugins/claude-config-maintainer/agents/maintainer.md
View File

@@ -277,6 +277,39 @@ Every CLAUDE.md should have:
1. **Project Overview** - What is this?
2. **Quick Start** - How do I build/test/run?
3. **Important Rules** - What must I NOT do?
4. **Pre-Change Protocol** - Mandatory dependency check before code changes
### Pre-Change Protocol Section (MANDATORY)
**This section is REQUIRED in every CLAUDE.md.** It ensures Claude performs comprehensive dependency analysis before making any code changes.
```markdown
## ⛔ MANDATORY: Before Any Code Change
**Claude MUST show this checklist BEFORE editing any file:**
### 1. Impact Search Results
Run and show output of:
```bash
grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
```
### 2. Files That Will Be Affected
Numbered list of every file to be modified, with the specific change for each.
### 3. Files Searched But Not Changed (and why)
Proof that related files were checked and determined unchanged.
### 4. Documentation That References This
List of docs that mention this feature/script/function.
**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
### After Changes
Run the same grep and show results proving no references remain unaddressed.
```
**When analyzing a CLAUDE.md, flag as HIGH priority issue if this section is missing.**
### Optional Sections (as needed)

37
plugins/claude-config-maintainer/commands/analyze.md
View File

@@ -59,6 +59,7 @@ Analyze the CLAUDE.md file in this project
- Quick start commands documented
- Critical rules highlighted
- Key workflows covered
- **Pre-Change Protocol section present** (MANDATORY - see below)
### Conciseness (25 points)
- No unnecessary repetition
@@ -66,6 +67,42 @@ Analyze the CLAUDE.md file in this project
- Appropriate length for project size
- No generic filler content
## Pre-Change Protocol Check (MANDATORY)
**This check is CRITICAL.** The Pre-Change Protocol section ensures Claude performs comprehensive dependency analysis before making any code changes, preventing missed references and incomplete updates.
### What to Check
Search CLAUDE.md for:
- Section header containing "Pre-Change" or "Before Any Code Change"
- References to `grep -rn` or impact search
- Checklist with "Files That Will Be Affected"
- Requirement for user verification before proceeding
### If Missing
**Flag as HIGH PRIORITY issue:**
```
1. [HIGH] Missing Pre-Change Protocol section
CLAUDE.md lacks mandatory dependency-check protocol.
Impact: Claude may miss file references when making changes,
leading to broken dependencies and incomplete updates.
Recommendation: Add Pre-Change Protocol section immediately.
This is the #1 cause of cascading bugs from incomplete changes.
```
### Required Section Content
The Pre-Change Protocol section must include:
1. Requirement to run grep search and show results
2. List of files that will be affected
3. List of files searched but not changed (with reasoning)
4. Documentation that references the change target
5. User verification checkpoint before proceeding
6. Post-change verification step
## Plugin Integration Analysis
After the content analysis, the command detects and analyzes marketplace plugin integration:

35
plugins/claude-config-maintainer/commands/init.md
View File

@@ -139,6 +139,7 @@ For small projects or when starting fresh:
- Project Overview (required)
- Quick Start (required)
- Critical Rules (required)
- **Pre-Change Protocol (required)**
### Standard Template (default)
For typical projects:
@@ -146,6 +147,7 @@ For typical projects:
- Quick Start
- Architecture
- Critical Rules
- **Pre-Change Protocol**
- Common Operations
- File Structure
@@ -153,11 +155,44 @@ For typical projects:
For large or complex projects:
- All standard sections plus:
- Detailed Architecture
- **Pre-Change Protocol**
- Troubleshooting
- Integration Points
- Development Workflow
- Deployment Notes
### Pre-Change Protocol Section (MANDATORY in ALL templates)
**This section MUST be included in every generated CLAUDE.md:**
```markdown
## ⛔ MANDATORY: Before Any Code Change
**Claude MUST show this checklist BEFORE editing any file:**
### 1. Impact Search Results
Run and show output of:
\`\`\`bash
grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
\`\`\`
### 2. Files That Will Be Affected
Numbered list of every file to be modified, with the specific change for each.
### 3. Files Searched But Not Changed (and why)
Proof that related files were checked and determined unchanged.
### 4. Documentation That References This
List of docs that mention this feature/script/function.
**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
### After Changes
Run the same grep and show results proving no references remain unaddressed.
```
**Rationale:** This protocol prevents incomplete changes where Claude modifies some files but misses others that reference the same code, causing cascading bugs.
## Auto-Detection
The command automatically detects:

44
plugins/claude-config-maintainer/commands/optimize.md
View File

@@ -56,6 +56,7 @@ Or specify specific optimizations:
### Enhance
- Add missing essential sections
- **Add Pre-Change Protocol if missing (HIGH PRIORITY)**
- Improve unclear instructions
- Add helpful examples
- Highlight critical rules
@@ -158,6 +159,49 @@ Backup saved to: .claude/backups/CLAUDE.md.2025-01-18
| `--preserve-comments` | Keep all existing comments |
| `--section=NAME` | Optimize specific section only |
## Pre-Change Protocol (Mandatory Addition)
**If CLAUDE.md is missing the Pre-Change Protocol section, optimization MUST add it.**
This is the highest priority enhancement because it prevents cascading bugs from incomplete code changes.
### Detection
Search CLAUDE.md for:
- "Pre-Change" or "Before Any Code Change" in headers
- References to impact search or grep verification
- User verification checkpoint
### If Missing
Add this section (position: after Critical Rules, before Common Operations):
```markdown
## ⛔ MANDATORY: Before Any Code Change
**Claude MUST show this checklist BEFORE editing any file:**
### 1. Impact Search Results
Run and show output of:
\`\`\`bash
grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
\`\`\`
### 2. Files That Will Be Affected
Numbered list of every file to be modified, with the specific change for each.
### 3. Files Searched But Not Changed (and why)
Proof that related files were checked and determined unchanged.
### 4. Documentation That References This
List of docs that mention this feature/script/function.
**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
### After Changes
Run the same grep and show results proving no references remain unaddressed.
```
## When to Use
Run `/config-optimize` when:

23
plugins/projman/hooks/startup-check.sh
View File

@@ -7,29 +7,6 @@ PREFIX="[projman]"
# Calculate paths
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(realpath "$0")")")}"
# Marketplace root is 2 levels up from plugin root (plugins/projman -> .)
MARKETPLACE_ROOT="$(dirname "$(dirname "$PLUGIN_ROOT")")"
VENV_REPAIR_SCRIPT="$MARKETPLACE_ROOT/scripts/venv-repair.sh"
# ============================================================================
# Auto-repair MCP venvs (runs before other checks)
# ============================================================================
if [[ -x "$VENV_REPAIR_SCRIPT" ]]; then
# Run venv repair - this creates symlinks to cached venvs
# Only outputs messages if something needed fixing
"$VENV_REPAIR_SCRIPT" 2>/dev/null || {
echo "$PREFIX MCP venv setup failed - run: cd $MARKETPLACE_ROOT && ./scripts/setup-venvs.sh"
exit 0
}
else
# Fallback: just check if venv exists
VENV_PATH="$PLUGIN_ROOT/mcp-servers/gitea/.venv/bin/python"
if [[ ! -f "$VENV_PATH" ]]; then
echo "$PREFIX MCP venvs missing - run setup.sh from installed marketplace"
exit 0
fi
fi
# Check git remote vs .env config (only if .env exists)
if [[ -f ".env" ]]; then

29
scripts/post-update.sh
View File

@@ -6,9 +6,10 @@
#
# This script:
# 1. Clears Claude plugin cache (forces fresh .mcp.json reads)
# 2. Restores MCP venv symlinks (instant if cache exists)
# 3. Creates venvs in external cache if missing (first run only)
# 4. Shows recent changelog updates
# 2. Shows recent changelog updates
#
# NOTE: This script does NOT touch .venv directories.
# If venvs are missing, run ./scripts/setup.sh manually.
#
set -euo pipefail
@@ -22,13 +23,11 @@ REPO_ROOT="$(dirname "$SCRIPT_DIR")"
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
RED='\033[0;31m'
NC='\033[0m'
log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
log_success() { echo -e "${GREEN}[OK]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
check_changelog() {
if [[ -f "$REPO_ROOT/CHANGELOG.md" ]]; then
@@ -52,35 +51,21 @@ main() {
# Clear Claude plugin cache to force fresh .mcp.json reads
# This cache holds versioned copies that become stale after updates
# NOTE: This does NOT touch .venv directories
if [[ -d "$CLAUDE_PLUGIN_CACHE" ]]; then
log_info "Clearing Claude plugin cache..."
rm -rf "$CLAUDE_PLUGIN_CACHE"
log_success "Plugin cache cleared"
fi
# Run venv-repair.sh to restore symlinks to external cache
# This is instant if cache exists, or does full setup on first run
if [[ -x "$SCRIPT_DIR/venv-repair.sh" ]]; then
log_info "Restoring MCP venv symlinks..."
if "$SCRIPT_DIR/venv-repair.sh"; then
log_success "MCP venvs ready"
else
log_error "MCP venv setup failed"
log_warn "Run: $SCRIPT_DIR/setup-venvs.sh for full setup"
exit 1
fi
else
log_error "venv-repair.sh not found at $SCRIPT_DIR"
exit 1
fi
check_changelog
echo ""
log_success "Post-update complete!"
echo ""
echo "IMPORTANT: Restart Claude Code for changes to take effect."
echo "MCP servers will work immediately on next session start."
echo ""
echo "If MCP servers are not working, run: ./scripts/setup.sh"
}
main "$@"

169
scripts/venv-repair.sh
View File

@@ -1,169 +0,0 @@
#!/usr/bin/env bash
#
# venv-repair.sh - Fast MCP venv auto-repair for SessionStart hooks
#
# This script is designed to run at session start. It:
# 1. Checks if venvs exist in external cache (~/.cache/claude-mcp-venvs/)
# 2. Creates symlinks from marketplace to cache (instant operation)
# 3. Only runs pip install if cache is missing (first install)
#
# Output format: All messages prefixed with [mcp-venv] for hook display
#
# Usage:
# ./scripts/venv-repair.sh # Auto-repair (default)
# ./scripts/venv-repair.sh --silent # Silent mode (no output unless error)
#
set -euo pipefail
# ============================================================================
# Configuration
# ============================================================================
PREFIX="[mcp-venv]"
VENV_CACHE_DIR="${HOME}/.cache/claude-mcp-venvs/leo-claude-mktplace"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(dirname "$SCRIPT_DIR")"
# MCP servers
MCP_SERVERS=(gitea netbox data-platform viz-platform contract-validator)
# Parse args
SILENT=false
[[ "${1:-}" == "--silent" ]] && SILENT=true
log() {
[[ "$SILENT" == true ]] && return
echo "$PREFIX $1"
}
log_error() {
echo "$PREFIX ERROR: $1" >&2
}
# ============================================================================
# Check if all venvs exist in cache
# ============================================================================
cache_complete() {
for server in "${MCP_SERVERS[@]}"; do
local venv_python="$VENV_CACHE_DIR/$server/.venv/bin/python"
[[ ! -f "$venv_python" ]] && return 1
done
return 0
}
# ============================================================================
# Create symlinks from marketplace to cache
# ============================================================================
create_symlink() {
local server_name="$1"
local server_path="$REPO_ROOT/mcp-servers/$server_name"
local venv_cache="$VENV_CACHE_DIR/$server_name/.venv"
local venv_link="$server_path/.venv"
# Skip if server doesn't exist
[[ ! -d "$server_path" ]] && return 0
# Skip if cache doesn't exist
[[ ! -d "$venv_cache" ]] && return 1
# Already correct symlink?
if [[ -L "$venv_link" ]]; then
local target
target=$(readlink "$venv_link")
[[ "$target" == "$venv_cache" ]] && return 0
rm "$venv_link"
elif [[ -d "$venv_link" ]]; then
# Old venv directory exists - back it up or remove
rm -rf "$venv_link"
fi
# Create symlink
ln -s "$venv_cache" "$venv_link"
return 0
}
create_all_symlinks() {
local created=0
for server in "${MCP_SERVERS[@]}"; do
if create_symlink "$server"; then
((created++)) || true
fi
done
[[ $created -gt 0 ]] && log "Restored $created venv symlinks"
}
# ============================================================================
# Full setup (only if cache missing)
# ============================================================================
setup_server() {
local server_name="$1"
local server_path="$REPO_ROOT/mcp-servers/$server_name"
local venv_path="$VENV_CACHE_DIR/$server_name/.venv"
[[ ! -d "$server_path" ]] && return 0
mkdir -p "$VENV_CACHE_DIR/$server_name"
# Create venv
if [[ ! -d "$venv_path" ]]; then
python3 -m venv "$venv_path"
fi
# Install dependencies
# shellcheck disable=SC1091
source "$venv_path/bin/activate"
pip install -q --upgrade pip
if [[ -f "$server_path/requirements.txt" ]]; then
pip install -q -r "$server_path/requirements.txt"
fi
if [[ -f "$server_path/pyproject.toml" ]]; then
pip install -q -e "$server_path"
fi
deactivate
# Save hash for future quick checks
local hash_file="$VENV_CACHE_DIR/$server_name/.requirements_hash"
{
if [[ -f "$server_path/requirements.txt" ]]; then
cat "$server_path/requirements.txt"
fi
if [[ -f "$server_path/pyproject.toml" ]]; then
cat "$server_path/pyproject.toml"
fi
echo "" # Ensure non-empty input for sha256sum
} | sha256sum | cut -d' ' -f1 > "$hash_file"
}
full_setup() {
log "First run - setting up MCP venvs (this only happens once)..."
for server in "${MCP_SERVERS[@]}"; do
log " Setting up $server..."
setup_server "$server"
done
log "Setup complete. Future sessions will be instant."
}
# ============================================================================
# Main
# ============================================================================
main() {
# Fast path: cache exists, just ensure symlinks
if cache_complete; then
create_all_symlinks
exit 0
fi
# Slow path: need to create venvs (first install)
full_setup
create_all_symlinks
}
main "$@"