From b13ffce0a0f4f3dc2d3c83d8cd219a296ef2cee1 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sat, 24 Jan 2026 12:57:32 -0500 Subject: [PATCH 1/3] fix: remove destructive cache-clear instruction from CLAUDE.md The CLAUDE.md mandatory rule instructed clearing the plugin cache mid-session, which breaks all MCP tools that were already loaded. MCP tools are loaded with absolute paths to the venv, and deleting the cache removes the venv while the session still references it. Changes: - CLAUDE.md: Replace "ALWAYS CLEAR CACHE" with "VERIFY AND RESTART" - verify-hooks.sh: Change cache existence from error to info message - DEBUGGING-CHECKLIST.md: Add section explaining cache timing Fixes #145 Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 31 +++++++++++++++---------- docs/DEBUGGING-CHECKLIST.md | 45 +++++++++++++++++++++++++++++++++++++ scripts/verify-hooks.sh | 8 +++---- 3 files changed, 68 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d80ad4f..8cb14d6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,11 +31,16 @@ This file provides guidance to Claude Code when working with code in this reposi - If user asks for output, show the OUTPUT - **Don't interpret or summarize unless asked** -### 5. AFTER PLUGIN UPDATES - ALWAYS CLEAR CACHE -```bash -rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/ -./scripts/verify-hooks.sh -``` +### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART + +**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded. + +1. Run `./scripts/verify-hooks.sh` to check hook types +2. If changes affect MCP servers or hooks, inform the user: + > "Plugin changes require a session restart to take effect. Please restart Claude Code." +3. Cache clearing is ONLY safe **before** starting a new session (not during) + +See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing. **FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE** @@ -125,7 +130,9 @@ leo-claude-mktplace/ │ └── project-hygiene/ ├── scripts/ │ ├── setup.sh, post-update.sh -│ └── validate-marketplace.sh # Marketplace compliance validation +│ ├── validate-marketplace.sh # Marketplace compliance validation +│ ├── verify-hooks.sh # Verify all hooks are command type +│ └── check-venv.sh # Check MCP server venvs exist └── docs/ ├── CANONICAL-PATHS.md # Single source of truth for paths └── CONFIGURATION.md # Centralized configuration guide @@ -172,12 +179,12 @@ leo-claude-mktplace/ | Category | Tools | |----------|-------| -| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` | -| Labels | `get_labels`, `suggest_labels`, `create_label` | -| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` | -| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` | -| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` | -| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` *(NEW v3.0.0)* | +| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`, `aggregate_issues` | +| Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` | +| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` | +| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` | +| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons` | +| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` | | Validation | `validate_repo_org`, `get_branch_protection` | ### Hybrid Configuration diff --git a/docs/DEBUGGING-CHECKLIST.md b/docs/DEBUGGING-CHECKLIST.md index e0a442a..e4eb2ad 100644 --- a/docs/DEBUGGING-CHECKLIST.md +++ b/docs/DEBUGGING-CHECKLIST.md @@ -197,6 +197,51 @@ echo -e "\n=== Config Files ===" --- +## Cache Clearing: When It's Safe vs Destructive + +**⚠️ CRITICAL: Never clear plugin cache mid-session.** + +### Why Cache Clearing Breaks MCP Tools + +When Claude Code starts a session: +1. MCP tools are loaded from the cache directory +2. Tool definitions include **absolute paths** to the venv (e.g., `~/.claude/plugins/cache/.../venv/`) +3. These paths are cached in the session memory +4. Deleting the cache removes the venv, but the session still references the old paths +5. Any MCP tool making HTTP requests fails with TLS certificate errors + +### When Cache Clearing is SAFE + +| Scenario | Safe? | Action | +|----------|-------|--------| +| Before starting Claude Code | ✅ Yes | Clear cache, then start session | +| Between sessions | ✅ Yes | Clear cache after `/exit`, before next session | +| During a session | ❌ NO | Never - will break MCP tools | +| After plugin source edits | ❌ NO | Restart session instead | + +### Recovery: MCP Tools Broken Mid-Session + +If you accidentally cleared cache during a session and MCP tools fail: + +``` +Error: Could not find a suitable TLS CA certificate bundle, invalid path: +/home/.../.claude/plugins/cache/.../certifi/cacert.pem +``` + +**Fix:** +1. Exit the current session (`/exit` or Ctrl+C) +2. Start a new Claude Code session +3. MCP tools will reload from the reinstalled cache + +### Correct Workflow for Plugin Development + +1. Make changes to plugin source files +2. Run `./scripts/verify-hooks.sh` (verifies hook types) +3. Tell user: "Please restart Claude Code for changes to take effect" +4. **Do NOT clear cache** - session restart handles reloading + +--- + ## Automated Diagnostics Use these commands for automated checking: diff --git a/scripts/verify-hooks.sh b/scripts/verify-hooks.sh index bb6fff8..7247493 100755 --- a/scripts/verify-hooks.sh +++ b/scripts/verify-hooks.sh @@ -15,11 +15,11 @@ for f in $(find ~/.claude -name "hooks.json" 2>/dev/null); do fi done -# Check cache specifically +# Note about cache (informational only - do NOT clear mid-session) if [ -d ~/.claude/plugins/cache/leo-claude-mktplace ]; then - echo "❌ CACHE EXISTS: ~/.claude/plugins/cache/leo-claude-mktplace" - echo " Run: rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/" - FAILED=1 + echo "ℹ️ Cache exists: ~/.claude/plugins/cache/leo-claude-mktplace" + echo " (This is normal - do NOT clear mid-session or MCP tools will break)" + echo " To apply plugin changes: restart Claude Code session" fi # Verify installed hooks are command type From ee3268fbe09e231db331aefa3f14c9220bdf1240 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sat, 24 Jan 2026 13:08:06 -0500 Subject: [PATCH 2/3] feat: add versioning workflow with release script - Add scripts/release.sh for consistent version releases - Fix CHANGELOG.md: consolidate all changes under [Unreleased] - Update CLAUDE.md with comprehensive versioning documentation - Include all commits since v3.1.1 in [Unreleased] section The release script ensures version consistency across: - Git tags - README.md title - marketplace.json version - CHANGELOG.md sections Addresses #143 Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 39 ++++++++++ CLAUDE.md | 55 +++++++++++++-- scripts/release.sh | 172 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 260 insertions(+), 6 deletions(-) create mode 100755 scripts/release.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 996f66e..dc9aea0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,45 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +## [Unreleased] + +### Added +- **git-flow:** `/commit` now detects protected branches before committing + - Warns when on protected branch (main, master, development, staging, production) + - Offers to create feature branch automatically instead of committing directly + - Configurable via `GIT_PROTECTED_BRANCHES` environment variable +- **netbox:** Platform and primary_ip parameters added to device update tools +- **claude-config-maintainer:** Auto-enforce mandatory behavior rules via SessionStart hook +- **scripts:** `release.sh` - Versioning workflow script for consistent releases +- **scripts:** `verify-hooks.sh` - Verify all hooks are command type + +### Changed +- **doc-guardian:** Hook switched from `prompt` type to `command` type + - Prompt hooks unreliable - Claude ignores explicit instructions + - New `notify.sh` bash script guarantees exact output behavior + - Only notifies for config file changes (commands/, agents/, skills/, hooks/) + - Silent exit for all other files - no blocking possible +- **All hooks:** Converted to command type with stricter plugin prefix enforcement + - All hooks now mandate `[plugin-name]` prefix with "NO EXCEPTIONS" rule + - Simplified output formats with word limits + - Consistent structure across projman, pr-review, code-sentinel, doc-guardian +- **CLAUDE.md:** Replaced destructive "ALWAYS CLEAR CACHE" rule with "VERIFY AND RESTART" + - Cache clearing mid-session breaks MCP tools + - Added guidance for proper plugin development workflow + +### Fixed +- **cmdb-assistant:** Complete MCP tool schemas for update operations (#138) +- **netbox:** Shorten tool names to meet 64-char API limit (#134) +- **cmdb-assistant:** Correct NetBox API URL format in setup wizard (#132) +- **gitea/projman:** Type safety for `create_label_smart`, curl-based debug-report (#124) +- **netbox:** Add diagnostic logging for JSON parse errors (#121) +- **labels:** Add duplicate check before creating labels (#116) +- **hooks:** Convert ALL hooks to command type with proper prefixes (#114) +- Protected branch workflow: Claude no longer commits directly to protected branches (fixes #109) +- doc-guardian hook no longer blocks workflow (fixes #110) + +--- + ## [3.1.1] - 2026-01-22 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 8cb14d6..9c3cbae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -293,13 +293,56 @@ See `docs/DEBUGGING-CHECKLIST.md` for systematic troubleshooting. - `/debug-report` - Run full diagnostics, create issue if needed - `/debug-review` - Investigate and propose fixes -## Versioning Rules +## Versioning Workflow -- 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 +This project follows [SemVer](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com). + +### Version Locations (must stay in sync) + +| Location | Format | Example | +|----------|--------|---------| +| Git tags | `vX.Y.Z` | `v3.2.0` | +| README.md title | `# Leo Claude Marketplace - vX.Y.Z` | `v3.2.0` | +| marketplace.json | `"version": "X.Y.Z"` | `3.2.0` | +| CHANGELOG.md | `## [X.Y.Z] - YYYY-MM-DD` | `[3.2.0] - 2026-01-24` | + +### During Development + +**All changes go under `[Unreleased]` in CHANGELOG.md.** Never create a versioned section until release time. + +```markdown +## [Unreleased] + +### Added +- New feature description + +### Fixed +- Bug fix description +``` + +### Creating a Release + +Use the release script to ensure consistency: + +```bash +./scripts/release.sh 3.2.0 +``` + +The script will: +1. Validate `[Unreleased]` section has content +2. Replace `[Unreleased]` with `[3.2.0] - YYYY-MM-DD` +3. Update README.md title +4. Update marketplace.json version +5. Commit and create git tag + +### SemVer Guidelines + +| Change Type | Version Bump | Example | +|-------------|--------------|---------| +| Bug fixes only | PATCH (x.y.**Z**) | 3.1.1 → 3.1.2 | +| New features (backwards compatible) | MINOR (x.**Y**.0) | 3.1.2 → 3.2.0 | +| Breaking changes | MAJOR (**X**.0.0) | 3.2.0 → 4.0.0 | --- -**Last Updated:** 2026-01-23 +**Last Updated:** 2026-01-24 diff --git a/scripts/release.sh b/scripts/release.sh new file mode 100755 index 0000000..cf22a71 --- /dev/null +++ b/scripts/release.sh @@ -0,0 +1,172 @@ +#!/bin/bash +# release.sh - Create a new release with version consistency +# +# Usage: ./scripts/release.sh X.Y.Z +# +# This script ensures all version references are updated consistently: +# 1. CHANGELOG.md - [Unreleased] becomes [X.Y.Z] - YYYY-MM-DD +# 2. README.md - Title updated to vX.Y.Z +# 3. marketplace.json - version field updated +# 4. Git commit and tag created +# +# Prerequisites: +# - Clean working directory (no uncommitted changes) +# - [Unreleased] section in CHANGELOG.md with content +# - On development branch + +set -e + +VERSION=$1 +DATE=$(date +%Y-%m-%d) + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +error() { echo -e "${RED}ERROR: $1${NC}" >&2; exit 1; } +warn() { echo -e "${YELLOW}WARNING: $1${NC}"; } +success() { echo -e "${GREEN}$1${NC}"; } +info() { echo -e "$1"; } + +# Validate arguments +if [ -z "$VERSION" ]; then + echo "Usage: ./scripts/release.sh X.Y.Z" + echo "" + echo "Example: ./scripts/release.sh 3.2.0" + echo "" + echo "This will:" + echo " 1. Update CHANGELOG.md [Unreleased] -> [X.Y.Z] - $(date +%Y-%m-%d)" + echo " 2. Update README.md title to vX.Y.Z" + echo " 3. Update marketplace.json version to X.Y.Z" + echo " 4. Commit with message 'chore: release vX.Y.Z'" + echo " 5. Create git tag vX.Y.Z" + exit 1 +fi + +# Validate version format +if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + error "Invalid version format. Use X.Y.Z (e.g., 3.2.0)" +fi + +# Check we're in the right directory +if [ ! -f "CHANGELOG.md" ] || [ ! -f "README.md" ] || [ ! -f ".claude-plugin/marketplace.json" ]; then + error "Must run from repository root (CHANGELOG.md, README.md, .claude-plugin/marketplace.json must exist)" +fi + +# Check for clean working directory +if [ -n "$(git status --porcelain)" ]; then + warn "Working directory has uncommitted changes" + echo "" + git status --short + echo "" + read -p "Continue anyway? [y/N] " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + exit 1 + fi +fi + +# Check current branch +BRANCH=$(git branch --show-current) +if [ "$BRANCH" != "development" ] && [ "$BRANCH" != "main" ]; then + warn "Not on development or main branch (current: $BRANCH)" + read -p "Continue anyway? [y/N] " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + exit 1 + fi +fi + +# Check [Unreleased] section has content +if ! grep -q "## \[Unreleased\]" CHANGELOG.md; then + error "CHANGELOG.md missing [Unreleased] section" +fi + +# Check if tag already exists +if git tag -l | grep -q "^v$VERSION$"; then + error "Tag v$VERSION already exists" +fi + +info "" +info "=== Release v$VERSION ===" +info "" + +# Show what will change +info "Changes to be made:" +info " CHANGELOG.md: [Unreleased] -> [$VERSION] - $DATE" +info " README.md: title -> v$VERSION" +info " marketplace.json: version -> $VERSION" +info " Git: commit + tag v$VERSION" +info "" + +# Preview CHANGELOG [Unreleased] content +info "Current [Unreleased] content:" +info "---" +sed -n '/^## \[Unreleased\]/,/^## \[/p' CHANGELOG.md | head -30 +info "---" +info "" + +read -p "Proceed with release? [y/N] " -n 1 -r +echo +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + info "Aborted" + exit 0 +fi + +info "" +info "Updating files..." + +# 1. Update CHANGELOG.md +# Replace [Unreleased] with [X.Y.Z] - DATE and add new [Unreleased] section +sed -i "s/^## \[Unreleased\]$/## [Unreleased]\n\n*Changes staged for the next release*\n\n---\n\n## [$VERSION] - $DATE/" CHANGELOG.md + +# Remove the placeholder text if it exists after the new [Unreleased] +sed -i '/^\*Changes staged for the next release\*$/d' CHANGELOG.md + +# Clean up any double blank lines +sed -i '/^$/N;/^\n$/d' CHANGELOG.md + +success " CHANGELOG.md updated" + +# 2. Update README.md title +sed -i "s/^# Leo Claude Marketplace - v[0-9]\+\.[0-9]\+\.[0-9]\+$/# Leo Claude Marketplace - v$VERSION/" README.md +success " README.md updated" + +# 3. Update marketplace.json version +sed -i "s/\"version\": \"[0-9]\+\.[0-9]\+\.[0-9]\+\"/\"version\": \"$VERSION\"/" .claude-plugin/marketplace.json +success " marketplace.json updated" + +info "" +info "Files updated. Review changes:" +info "" +git diff --stat +info "" +git diff CHANGELOG.md | head -40 +info "" + +read -p "Commit and tag? [y/N] " -n 1 -r +echo +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + warn "Changes made but not committed. Run 'git checkout -- .' to revert." + exit 0 +fi + +# Commit +git add CHANGELOG.md README.md .claude-plugin/marketplace.json +git commit -m "chore: release v$VERSION" +success " Committed" + +# Tag +git tag "v$VERSION" +success " Tagged v$VERSION" + +info "" +success "=== Release v$VERSION created ===" +info "" +info "Next steps:" +info " 1. Review the commit: git show HEAD" +info " 2. Push to remote: git push && git push --tags" +info " 3. Merge to main if on development branch" +info "" From bcde33c7d0deb25e94f89bdfae7e9efa271f195a Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sat, 24 Jan 2026 13:08:45 -0500 Subject: [PATCH 3/3] chore: release v3.2.0 Version 3.2.0 includes: - New features: netbox device params, claude-config-maintainer auto-enforce - Bug fixes: cmdb-assistant schemas, netbox tool names, API URLs - All hooks converted to command type - Versioning workflow with release script Co-Authored-By: Claude Opus 4.5 --- .claude-plugin/marketplace.json | 2 +- CHANGELOG.md | 6 ++++++ README.md | 15 ++++++++------- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 23a5079..776e020 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "metadata": { "description": "Project management plugins with Gitea and NetBox integrations", - "version": "3.1.0" + "version": "3.2.0" }, "plugins": [ { diff --git a/CHANGELOG.md b/CHANGELOG.md index dc9aea0..51d2e6c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +*Changes staged for the next release* + +--- + +## [3.2.0] - 2026-01-24 + ### Added - **git-flow:** `/commit` now detects protected branches before committing - Warns when on protected branch (main, master, development, staging, production) diff --git a/README.md b/README.md index d9124de..4442123 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Leo Claude Marketplace - v3.1.1 +# Leo Claude Marketplace - v3.2.0 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows. @@ -106,11 +106,11 @@ Full Gitea API integration for project management. | Category | Tools | |----------|-------| -| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` | -| Labels | `get_labels`, `suggest_labels`, `create_label` | -| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` | -| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` | -| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` | +| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`, `aggregate_issues` | +| Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` | +| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons` | +| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` | +| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` | | **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` *(NEW in v3.0.0)* | | Validation | `validate_repo_org`, `get_branch_protection` | @@ -245,7 +245,8 @@ leo-claude-mktplace/ ├── docs/ # Documentation │ ├── CANONICAL-PATHS.md # Path reference │ └── CONFIGURATION.md # Setup guide -└── scripts/ # Setup scripts +├── scripts/ # Setup scripts +└── CHANGELOG.md # Version history ``` ## Documentation