Compare commits
8 Commits
620173eef6
...
v3.1.1
| Author | SHA1 | Date | |
|---|---|---|---|
| 0d120bd041 | |||
| 508832dae1 | |||
| 0b23a02886 | |||
| 71987ee537 | |||
| b7829dca05 | |||
| 9b0e9a69b1 | |||
| ad0e14d07f | |||
| 7fd5fffedf |
20
CHANGELOG.md
20
CHANGELOG.md
@@ -4,6 +4,26 @@ 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/).
|
||||
|
||||
## [3.1.1] - 2026-01-22
|
||||
|
||||
### Added
|
||||
- **git-flow:** `/commit-sync` now prunes stale remote-tracking branches with `git fetch --prune`
|
||||
- **git-flow:** `/commit-sync` detects and reports local branches with deleted upstreams
|
||||
- **git-flow:** `/branch-cleanup` now handles stale branches (upstream gone) separately from merged branches
|
||||
- **git-flow:** New `GIT_CLEANUP_STALE` environment variable for stale branch cleanup control
|
||||
|
||||
### Changed
|
||||
- **All hooks:** Added `[plugin-name]` prefix to all hook messages for better identification
|
||||
- `[projman]`, `[pr-review]`, `[code-sentinel]`, `[doc-guardian]` prefixes
|
||||
- **doc-guardian:** Hook now notification-only (no file reads or blocking operations)
|
||||
- Suggests running `/doc-sync` instead of performing inline checks
|
||||
- Significantly reduces workflow interruption
|
||||
|
||||
### Fixed
|
||||
- doc-guardian hook no longer stalls workflow with deep file analysis
|
||||
|
||||
---
|
||||
|
||||
## [3.1.0] - 2026-01-21
|
||||
|
||||
### Added
|
||||
|
||||
85
CLAUDE.md
85
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
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Leo Claude Marketplace - v3.1.0
|
||||
# Leo Claude Marketplace - v3.1.1
|
||||
|
||||
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
|
||||
|
||||
|
||||
@@ -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` |
|
||||
|
||||
---
|
||||
|
||||
|
||||
213
docs/DEBUGGING-CHECKLIST.md
Normal file
213
docs/DEBUGGING-CHECKLIST.md
Normal file
@@ -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
|
||||
@@ -6,7 +6,7 @@
|
||||
"hooks": [
|
||||
{
|
||||
"type": "prompt",
|
||||
"prompt": "SECURITY CHECK - Before writing this code, scan for these patterns:\n\n**Critical (BLOCK if found):**\n- eval(), exec() with user input\n- SQL string concatenation (SQL injection)\n- shell=True with user input (command injection)\n- Hardcoded secrets (API keys, passwords, tokens)\n- Pickle/marshal deserialization of untrusted data\n- innerHTML/dangerouslySetInnerHTML with user content (XSS)\n\n**Warning (WARN but allow):**\n- subprocess without input validation\n- File operations without path sanitization\n- HTTP requests without timeout\n- Broad exception catches (except:)\n- Debug/print statements with sensitive data\n\n**Response:**\n- If CRITICAL found: STOP, explain the issue, suggest safe alternative\n- If WARNING found: Note it briefly, proceed with suggestion\n- If clean: Proceed silently (say nothing)\n\nDo NOT announce clean scans. Only speak if issues found."
|
||||
"prompt": "[code-sentinel] SECURITY CHECK - Before writing this code, scan for these patterns:\n\n**Critical (BLOCK if found):**\n- eval(), exec() with user input\n- SQL string concatenation (SQL injection)\n- shell=True with user input (command injection)\n- Hardcoded secrets (API keys, passwords, tokens)\n- Pickle/marshal deserialization of untrusted data\n- innerHTML/dangerouslySetInnerHTML with user content (XSS)\n\n**Warning (WARN but allow):**\n- subprocess without input validation\n- File operations without path sanitization\n- HTTP requests without timeout\n- Broad exception catches (except:)\n- Debug/print statements with sensitive data\n\n**Response:**\n- If CRITICAL found: STOP with '[code-sentinel] BLOCKED:', explain the issue, suggest safe alternative\n- If WARNING found: Note briefly with '[code-sentinel] WARNING:', proceed with suggestion\n- If clean: Proceed silently (say nothing)\n\nDo NOT announce clean scans. Only speak if issues found."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
"hooks": [
|
||||
{
|
||||
"type": "prompt",
|
||||
"prompt": "A file was just modified. Silently check if this change affects any documentation:\n\n1. If a code file changed: check if README, CLAUDE.md, docstrings, or API docs reference the modified functions/classes/configs\n2. If drift detected: briefly mention it to the user (e.g., 'Note: This change may require updating X documentation')\n3. Do NOT block the workflow - just inform\n\nDo NOT announce this check unless drift is found. Work silently."
|
||||
"prompt": "[doc-guardian] QUICK drift check (DO NOT block workflow):\n\n1. ONLY check if the modified file is referenced in README.md, CLAUDE.md, or API docs in the SAME directory\n2. Do NOT read files or perform deep analysis - just note potential drift based on file name/path\n3. If potential drift: output a single line like '[doc-guardian] Note: {filename} changed - may affect {doc}. Run /doc-sync to verify.'\n4. If no obvious drift: say nothing\n\nIMPORTANT: This is notification-only. Do NOT read documentation files, do NOT make changes, do NOT use any tools. Just a quick mental check based on the file path."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,12 +1,19 @@
|
||||
# /branch-cleanup - Clean Merged Branches
|
||||
# /branch-cleanup - Clean Merged and Stale Branches
|
||||
|
||||
## Purpose
|
||||
|
||||
Remove branches that have been merged, both locally and optionally on remote.
|
||||
Remove branches that have been merged OR whose remote tracking branch no longer exists, both locally and optionally on remote.
|
||||
|
||||
## Behavior
|
||||
|
||||
### Step 1: Identify Merged Branches
|
||||
### Step 1: Prune Remote Refs
|
||||
|
||||
```bash
|
||||
# Remove stale remote-tracking references
|
||||
git fetch --prune
|
||||
```
|
||||
|
||||
### Step 2: Identify Branches for Cleanup
|
||||
|
||||
```bash
|
||||
# Find merged local branches
|
||||
@@ -14,19 +21,26 @@ git branch --merged <base-branch>
|
||||
|
||||
# Find merged remote branches
|
||||
git branch -r --merged <base-branch>
|
||||
|
||||
# Find local branches with deleted upstreams (stale)
|
||||
git branch -vv | grep ': gone]'
|
||||
```
|
||||
|
||||
### Step 2: Present Findings
|
||||
### Step 3: Present Findings
|
||||
|
||||
```
|
||||
Found 5 merged branches:
|
||||
Found branches for cleanup:
|
||||
|
||||
Local:
|
||||
Merged (safe to delete):
|
||||
- feat/login-page (merged 3 days ago)
|
||||
- fix/typo-header (merged 1 week ago)
|
||||
- chore/deps-update (merged 2 weeks ago)
|
||||
|
||||
Remote:
|
||||
Stale (remote deleted):
|
||||
- feat/old-feature (upstream gone)
|
||||
- fix/already-merged (upstream gone)
|
||||
|
||||
Remote (merged into base):
|
||||
- origin/feat/login-page
|
||||
- origin/fix/typo-header
|
||||
|
||||
@@ -36,35 +50,40 @@ Protected (won't delete):
|
||||
- staging
|
||||
|
||||
Delete these branches?
|
||||
1. Delete all (local + remote)
|
||||
2. Delete local only
|
||||
3. Let me pick which ones
|
||||
4. Cancel
|
||||
1. Delete all (local merged + stale + remote)
|
||||
2. Delete merged only (skip stale)
|
||||
3. Delete stale only (upstream gone)
|
||||
4. Let me pick which ones
|
||||
5. Cancel
|
||||
```
|
||||
|
||||
### Step 3: Execute Cleanup
|
||||
### Step 4: Execute Cleanup
|
||||
|
||||
```bash
|
||||
# Delete local
|
||||
# Delete merged local branches
|
||||
git branch -d <branch-name>
|
||||
|
||||
# Delete remote
|
||||
# Delete stale local branches (force needed since no upstream)
|
||||
git branch -D <stale-branch-name>
|
||||
|
||||
# Delete remote branches
|
||||
git push origin --delete <branch-name>
|
||||
```
|
||||
|
||||
### Step 4: Report
|
||||
### Step 5: Report
|
||||
|
||||
```
|
||||
Cleanup complete:
|
||||
|
||||
Deleted local: 3 branches
|
||||
Deleted local (merged): 3 branches
|
||||
Deleted local (stale): 2 branches
|
||||
Deleted remote: 2 branches
|
||||
Skipped: 0 branches
|
||||
|
||||
Remaining local branches:
|
||||
- main
|
||||
- development
|
||||
- feat/current-work (not merged)
|
||||
- feat/current-work (not merged, has upstream)
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
@@ -74,20 +93,24 @@ Remaining local branches:
|
||||
| `GIT_DEFAULT_BASE` | `development` | Base branch for merge detection |
|
||||
| `GIT_PROTECTED_BRANCHES` | `main,master,development,staging,production` | Never delete these |
|
||||
| `GIT_AUTO_DELETE_REMOTE` | `false` | Auto-delete remote branches |
|
||||
| `GIT_CLEANUP_STALE` | `true` | Include stale branches (upstream gone) in cleanup |
|
||||
|
||||
## Safety
|
||||
|
||||
- Never deletes protected branches
|
||||
- Warns about unmerged branches
|
||||
- Warns about unmerged branches that still have upstreams
|
||||
- Confirms before deleting remote branches
|
||||
- Uses `-d` (safe delete) not `-D` (force delete)
|
||||
- Uses `-d` (safe delete) for merged branches
|
||||
- Uses `-D` (force delete) only for stale branches with confirmation
|
||||
- Stale branches are highlighted separately for review
|
||||
|
||||
## Output
|
||||
|
||||
On success:
|
||||
```
|
||||
Cleaned up:
|
||||
Local: 3 branches deleted
|
||||
Local (merged): 3 branches deleted
|
||||
Local (stale): 2 branches deleted
|
||||
Remote: 2 branches deleted
|
||||
|
||||
Repository is tidy!
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
Full sync operation: commit local changes, push to remote, and sync with upstream/base branch.
|
||||
Full sync operation: commit local changes, push to remote, sync with upstream/base branch, and clean up stale remote-tracking branches.
|
||||
|
||||
## Behavior
|
||||
|
||||
@@ -19,8 +19,8 @@ Push committed changes to remote branch.
|
||||
Pull latest from base branch and rebase/merge:
|
||||
|
||||
```bash
|
||||
# Fetch all
|
||||
git fetch --all
|
||||
# Fetch all with prune (removes stale remote-tracking refs)
|
||||
git fetch --all --prune
|
||||
|
||||
# Rebase on base branch
|
||||
git rebase origin/<base-branch>
|
||||
@@ -29,7 +29,26 @@ git rebase origin/<base-branch>
|
||||
git push --force-with-lease
|
||||
```
|
||||
|
||||
### Step 4: Report Status
|
||||
### Step 4: Detect Stale Local Branches
|
||||
|
||||
Check for local branches tracking deleted remotes:
|
||||
|
||||
```bash
|
||||
# Find local branches with gone upstreams
|
||||
git branch -vv | grep ': gone]'
|
||||
```
|
||||
|
||||
If stale branches found, report them:
|
||||
|
||||
```
|
||||
Stale local branches (remote deleted):
|
||||
- feat/old-feature (was tracking origin/feat/old-feature)
|
||||
- fix/merged-bugfix (was tracking origin/fix/merged-bugfix)
|
||||
|
||||
Run /branch-cleanup to remove these branches.
|
||||
```
|
||||
|
||||
### Step 5: Report Status
|
||||
|
||||
```
|
||||
Sync complete:
|
||||
@@ -40,6 +59,10 @@ Base: development @ xyz7890 (synced)
|
||||
|
||||
Your branch is up-to-date with development.
|
||||
No conflicts detected.
|
||||
|
||||
Cleanup:
|
||||
Remote refs pruned: 2
|
||||
Stale local branches: 2 (run /branch-cleanup to remove)
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
@@ -48,6 +71,7 @@ No conflicts detected.
|
||||
|----------|---------|-------------|
|
||||
| `GIT_DEFAULT_BASE` | `development` | Branch to sync with |
|
||||
| `GIT_SYNC_STRATEGY` | `rebase` | How to incorporate upstream changes |
|
||||
| `GIT_AUTO_PRUNE` | `true` | Auto-prune stale remote refs on sync |
|
||||
|
||||
## Conflict Handling
|
||||
|
||||
@@ -76,4 +100,5 @@ Pushed to: origin/feat/password-reset
|
||||
Synced with: development (xyz7890)
|
||||
|
||||
Status: Clean, up-to-date
|
||||
Stale branches: None (or N found - run /branch-cleanup)
|
||||
```
|
||||
|
||||
@@ -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 <org>/<repo> but .env has <old-org>/<old-repo>. 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": "[pr-review] 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: '[pr-review] MCP venvs missing - run setup.sh from installed marketplace location'.\n\n2. Check if the project git remote matches .env configuration (GITEA_ORG/GITEA_REPO). If mismatch, warn: '[pr-review] Git remote mismatch - run /project-sync'.\n\nStay silent if all checks pass or not applicable. Be quick and non-blocking."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -184,6 +184,10 @@ Use this exact template:
|
||||
|
||||
### Step 6: Create Issue in Marketplace
|
||||
|
||||
**First, check if MCP tools are available.** Attempt to use an MCP tool. If you receive "tool not found", "not in function list", or similar error, the MCP server is not accessible in this session - use the curl fallback.
|
||||
|
||||
#### Option A: MCP Available (preferred)
|
||||
|
||||
```
|
||||
mcp__plugin_projman_gitea__create_issue(
|
||||
repo=MARKETPLACE_REPO,
|
||||
@@ -195,6 +199,81 @@ mcp__plugin_projman_gitea__create_issue(
|
||||
|
||||
If labels don't exist, create issue without labels.
|
||||
|
||||
#### Option B: MCP Unavailable - Use curl Fallback
|
||||
|
||||
If MCP tools are not available (the very issue you may be diagnosing), use this fallback:
|
||||
|
||||
**1. Check for Gitea credentials:**
|
||||
|
||||
```bash
|
||||
if [[ -f ~/.config/claude/gitea.env ]]; then
|
||||
source ~/.config/claude/gitea.env
|
||||
echo "Credentials found. API URL: $GITEA_API_URL"
|
||||
else
|
||||
echo "No credentials at ~/.config/claude/gitea.env"
|
||||
fi
|
||||
```
|
||||
|
||||
**2. If credentials exist, create issue via curl with proper JSON escaping:**
|
||||
|
||||
Create secure temp files and save content:
|
||||
|
||||
```bash
|
||||
# Create temp files with restrictive permissions
|
||||
DIAG_TITLE=$(mktemp -p /tmp -m 600 diag-title.XXXXXX)
|
||||
DIAG_BODY=$(mktemp -p /tmp -m 600 diag-body.XXXXXX)
|
||||
DIAG_PAYLOAD=$(mktemp -p /tmp -m 600 diag-payload.XXXXXX)
|
||||
|
||||
# Save title
|
||||
echo "[Diagnostic] [summary of main failure]" > "$DIAG_TITLE"
|
||||
|
||||
# Save body (paste Step 5 content) - heredoc delimiter prevents shell expansion
|
||||
cat > "$DIAG_BODY" << 'DIAGNOSTIC_EOF'
|
||||
[Paste the full issue content from Step 5 here]
|
||||
DIAGNOSTIC_EOF
|
||||
```
|
||||
|
||||
Construct JSON safely using jq's --rawfile (avoids command substitution):
|
||||
|
||||
```bash
|
||||
# Build JSON payload using jq with --rawfile for safe content handling
|
||||
jq -n \
|
||||
--rawfile title "$DIAG_TITLE" \
|
||||
--rawfile body "$DIAG_BODY" \
|
||||
'{title: ($title | rtrimstr("\n")), body: $body}' > "$DIAG_PAYLOAD"
|
||||
|
||||
# Create issue using the JSON file
|
||||
curl -s -X POST "${GITEA_API_URL}/repos/${MARKETPLACE_REPO}/issues" \
|
||||
-H "Authorization: token ${GITEA_API_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @"$DIAG_PAYLOAD" | jq '.html_url // .'
|
||||
|
||||
# Secure cleanup
|
||||
rm -f "$DIAG_TITLE" "$DIAG_BODY" "$DIAG_PAYLOAD"
|
||||
```
|
||||
|
||||
**3. If no credentials found, save report locally:**
|
||||
|
||||
```bash
|
||||
REPORT_FILE=$(mktemp -p /tmp -m 600 diagnostic-report-XXXXXX.md)
|
||||
cat > "$REPORT_FILE" << 'DIAGNOSTIC_EOF'
|
||||
[Paste the full issue content from Step 5 here]
|
||||
DIAGNOSTIC_EOF
|
||||
echo "Report saved to: $REPORT_FILE"
|
||||
```
|
||||
|
||||
Then inform the user:
|
||||
|
||||
```
|
||||
MCP tools are unavailable and no Gitea credentials found at ~/.config/claude/gitea.env.
|
||||
|
||||
Diagnostic report saved to: [REPORT_FILE]
|
||||
|
||||
To create the issue manually:
|
||||
1. Configure credentials: See docs/CONFIGURATION.md
|
||||
2. Or create issue directly at: http://gitea.hotserv.cloud/[MARKETPLACE_REPO]/issues/new
|
||||
```
|
||||
|
||||
### Step 7: Report to User
|
||||
|
||||
Display summary:
|
||||
@@ -258,5 +337,6 @@ and I can create a manual bug report.
|
||||
- If not a git repo, ask user for the repository path
|
||||
|
||||
**MCP tools not available**
|
||||
- The projman plugin may not be properly installed
|
||||
- Check if .mcp.json exists and is configured
|
||||
- Use the curl fallback in Step 6, Option B
|
||||
- Requires Gitea credentials at `~/.config/claude/gitea.env`
|
||||
- If no credentials, report will be saved locally for manual submission
|
||||
|
||||
@@ -312,7 +312,12 @@ git push -u origin fix/issue-[NUMBER]-[brief-description]
|
||||
|
||||
3. Create PR via API or MCP tools
|
||||
|
||||
4. Add comment to original issue:
|
||||
4. **Switch back to development branch** (required for MCP issue operations):
|
||||
```bash
|
||||
git checkout development
|
||||
```
|
||||
|
||||
5. Add comment to original issue:
|
||||
```
|
||||
mcp__plugin_projman_gitea__add_comment(
|
||||
repo=REPO_NAME,
|
||||
|
||||
@@ -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 <org>/<repo> but .env has <old-org>/<old-repo>. 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": "[projman] 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: '[projman] MCP venvs missing - run setup.sh from installed marketplace location'.\n\n2. Check if the project git remote matches .env configuration (GITEA_ORG/GITEA_REPO). If mismatch, warn: '[projman] Git remote mismatch - run /project-sync'.\n\nStay silent if all checks pass or not applicable. Be quick and non-blocking."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
37
scripts/check-venv.sh
Executable file
37
scripts/check-venv.sh
Executable file
@@ -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
|
||||
Reference in New Issue
Block a user