personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
76105e98e064bae9f23f36c56891da9e5a38b7bc
leo-claude-mktplace/docs/CANONICAL-PATHS.md
lmiranda c9e054e013 fix(hooks): check venv cache path before marketplace path 
Startup hooks in data-platform and pr-review were checking for venvs
at the marketplace path (~/.claude/plugins/marketplaces/.../mcp-servers/)
which gets wiped on updates. The actual venvs live in the cache directory
(~/.cache/claude-mcp-venvs/) which survives updates.

This caused false "MCP venv missing" errors even when venvs existed,
wasting hours of debugging time.

Fixed hooks now check cache path first, matching the pattern used
by run.sh scripts.

Also updated docs/CANONICAL-PATHS.md with the correct venv path pattern
to prevent future occurrences.

Lesson learned: lessons/patterns/startup-hooks-must-check-venv-cache-path-first

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-02 22:13:40 -05:00

320 lines
12 KiB
Markdown
Raw Blame History

# Canonical Paths - SINGLE SOURCE OF TRUTH
**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
Last Updated: 2026-01-30 (v5.4.1)
---
## Repository Root Structure
```
leo-claude-mktplace/
├── .claude/ # Claude Code local settings
├── .claude-plugin/ # Marketplace manifest
│ └── marketplace.json
├── .scratch/ # Transient work (auto-cleaned)
├── docs/ # All documentation
│ ├── architecture/ # Draw.io diagrams and specs
│ ├── CANONICAL-PATHS.md # This file - single source of truth
│ ├── COMMANDS-CHEATSHEET.md # All commands quick reference
│ ├── CONFIGURATION.md # Centralized configuration guide
│ ├── DEBUGGING-CHECKLIST.md # Systematic troubleshooting guide
│ └── UPDATING.md # Update guide
├── hooks/ # Shared hooks (if any)
├── mcp-servers/ # SHARED MCP servers (v3.0.0+)
│ ├── gitea/ # Gitea MCP server
│ │ ├── mcp_server/
│ │ │ ├── server.py
│ │ │ ├── gitea_client.py
│ │ │ ├── config.py
│ │ │ └── tools/
│ │ │ ├── issues.py
│ │ │ ├── labels.py
│ │ │ ├── wiki.py
│ │ │ ├── milestones.py
│ │ │ ├── dependencies.py
│ │ │ └── pull_requests.py # NEW in v3.0.0
│ │ ├── requirements.txt
│ │ └── .venv/
│ ├── netbox/ # NetBox MCP server
│ │ ├── mcp_server/
│ │ ├── requirements.txt
│ │ └── .venv/
│ ├── data-platform/ # Data engineering MCP (NEW v4.0.0)
│ │ ├── mcp_server/
│ │ │ ├── server.py
│ │ │ ├── pandas_tools.py
│ │ │ ├── postgres_tools.py
│ │ │ └── dbt_tools.py
│ │ ├── requirements.txt
│ │ └── .venv/
│ ├── contract-validator/ # Contract validation MCP (NEW v5.0.0)
│ │ ├── mcp_server/
│ │ │ ├── server.py
│ │ │ ├── parse_tools.py
│ │ │ ├── validation_tools.py
│ │ │ └── report_tools.py
│ │ ├── tests/
│ │ ├── requirements.txt
│ │ └── .venv/
│ └── viz-platform/ # Visualization MCP (NEW v4.1.0)
│ ├── mcp_server/
│ │ ├── server.py
│ │ ├── config.py
│ │ ├── component_registry.py
│ │ ├── dmc_tools.py
│ │ ├── chart_tools.py
│ │ ├── layout_tools.py
│ │ ├── theme_tools.py
│ │ ├── theme_store.py
│ │ └── page_tools.py
│ ├── registry/ # DMC component JSON registries
│ ├── tests/ # 94 tests
│ ├── requirements.txt
│ └── .venv/
├── plugins/ # ALL plugins
│ ├── projman/ # Sprint management
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ ├── skills/
│ │ └── claude-md-integration.md
│ ├── doc-guardian/ # Documentation drift detection
│ │ ├── .claude-plugin/
│ │ ├── hooks/
│ │ ├── commands/
│ │ ├── agents/
│ │ ├── skills/
│ │ └── claude-md-integration.md
│ ├── code-sentinel/ # Security scanning & refactoring
│ │ ├── .claude-plugin/
│ │ ├── hooks/
│ │ ├── commands/
│ │ ├── agents/
│ │ ├── skills/
│ │ └── claude-md-integration.md
│ ├── cmdb-assistant/ # NetBox CMDB integration
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ └── claude-md-integration.md
│ ├── claude-config-maintainer/
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ └── claude-md-integration.md
│ ├── project-hygiene/
│ │ ├── .claude-plugin/
│ │ ├── hooks/
│ │ └── claude-md-integration.md
│ ├── clarity-assist/
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ ├── skills/
│ │ └── claude-md-integration.md
│ ├── git-flow/
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ ├── skills/
│ │ └── claude-md-integration.md
│ ├── pr-review/
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ ├── skills/
│ │ └── claude-md-integration.md
│ ├── data-platform/
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ ├── hooks/
│ │ └── claude-md-integration.md
│ ├── contract-validator/
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ └── claude-md-integration.md
│ └── viz-platform/
│ ├── .claude-plugin/
│ ├── commands/
│ ├── agents/
│ ├── hooks/
│ └── claude-md-integration.md
├── scripts/ # Setup and maintenance scripts
│ ├── setup.sh # Initial setup (create venvs, config templates)
│ ├── 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 MCP server venvs (create only, never delete)
│ └── release.sh # Release automation with version bumping
├── CLAUDE.md
├── README.md
├── LICENSE
├── CHANGELOG.md
└── .gitignore
```
---
## Path Patterns (MANDATORY)
### Plugin Paths
| Context | Pattern | Example |
|---------|---------|---------|
| Plugin location | `plugins/{plugin-name}/` | `plugins/projman/` |
| Plugin manifest | `plugins/{plugin-name}/.claude-plugin/plugin.json` | `plugins/projman/.claude-plugin/plugin.json` |
| Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
| Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
| Plugin skills | `plugins/{plugin-name}/skills/` | `plugins/projman/skills/` |
| Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
### MCP Server Paths
MCP servers are **shared at repository root** and configured in `.mcp.json`.
| Context | Pattern | Example |
|---------|---------|---------|
| MCP configuration | `.mcp.json` | `.mcp.json` (at repo root) |
| Shared MCP server | `mcp-servers/{server}/` | `mcp-servers/gitea/` |
| MCP server code | `mcp-servers/{server}/mcp_server/` | `mcp-servers/gitea/mcp_server/` |
| MCP venv (local) | `mcp-servers/{server}/.venv/` | `mcp-servers/gitea/.venv/` |
**Note:** Plugins do NOT have their own `mcp-servers/` directories. All MCP servers are shared at root and configured via `.mcp.json`.
### MCP Venv Paths - CRITICAL
**Venvs live in a CACHE directory that SURVIVES marketplace updates.**
When checking for venvs, ALWAYS check in this order:
| Priority | Path | Survives Updates? |
|----------|------|-------------------|
| 1 (CHECK FIRST) | `~/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv/` | YES |
| 2 (fallback) | `{marketplace}/mcp-servers/{server}/.venv/` | NO |
**Why cache first?**
- Marketplace directory gets WIPED on every update/reinstall
- Cache directory SURVIVES updates
- False "venv missing" errors waste hours of debugging
**Pattern for hooks checking venvs:**
```bash
CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv/bin/python"
LOCAL_VENV="$MARKETPLACE_ROOT/mcp-servers/{server}/.venv/bin/python"
if [[ -f "$CACHE_VENV" ]]; then
VENV_PATH="$CACHE_VENV"
elif [[ -f "$LOCAL_VENV" ]]; then
VENV_PATH="$LOCAL_VENV"
else
echo "venv missing"
fi
```
**See lesson learned:** [Startup Hooks Must Check Venv Cache Path First](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/lessons/patterns/startup-hooks-must-check-venv-cache-path-first)
### Documentation Paths
| Type | Location |
|------|----------|
| Architecture diagrams | `docs/architecture/` |
| This file | `docs/CANONICAL-PATHS.md` |
| Update guide | `docs/UPDATING.md` |
| Configuration guide | `docs/CONFIGURATION.md` |
| Commands cheat sheet | `docs/COMMANDS-CHEATSHEET.md` |
| Debugging checklist | `docs/DEBUGGING-CHECKLIST.md` |
---
## Validation Rules
### Before Creating Any File
1. Check this file for the correct path pattern
2. Verify the parent directory exists in the structure above
3. If path not listed here, **STOP AND ASK**
### Before Generating Any Prompt
1. List all file paths the prompt will create/modify
2. Verify each path against patterns in this file
3. Show verification to user before proceeding
### Relative Path Calculation
From `.mcp.json` (at root) to `mcp-servers/gitea/`:
```
.mcp.json (at repository root)
→ Uses absolute installed path: ~/.claude/plugins/marketplaces/.../mcp-servers/gitea/run.sh
```
From `.claude-plugin/marketplace.json` to `plugins/projman/`:
```
.claude-plugin/marketplace.json
↑ marketplace.json is at repo root level
→ go down to plugins/projman/ (./plugins/projman/)
Result: ./plugins/projman
```
---
## Anti-Patterns (NEVER DO THIS)
| Wrong | Why | Correct |
|-------|-----|---------|
| `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` |
| `mcp-servers/` inside plugins | MCP servers are shared at root | Use root `mcp-servers/` |
| Plugin-level `.mcp.json` | MCP config is at root | Use root `.mcp.json` |
| Hardcoding absolute paths in source | Breaks portability | Use relative paths or `${CLAUDE_PLUGIN_ROOT}` |
---
## Architecture Note
MCP servers are **shared at repository root** and configured in a single `.mcp.json` file.
**Benefits:**
- Single source of truth for each MCP server
- Updates apply to all plugins automatically
- No duplication - clean plugin structure
- Simple configuration in one place
**Configuration:**
All MCP servers are defined in `.mcp.json` at repository root:
```json
{
"mcpServers": {
"gitea": { "command": ".../mcp-servers/gitea/run.sh" },
"netbox": { "command": ".../mcp-servers/netbox/run.sh" },
"data-platform": { "command": ".../mcp-servers/data-platform/run.sh" },
"viz-platform": { "command": ".../mcp-servers/viz-platform/run.sh" },
"contract-validator": { "command": ".../mcp-servers/contract-validator/run.sh" }
}
}
```
---
## Change Log
| Date | Change | By |
|------|--------|-----|
| 2026-01-30 | v5.5.0: Removed plugin-level mcp-servers symlinks - all MCP config now in root .mcp.json | Claude Code |
| 2026-01-26 | v5.0.0: Added contract-validator plugin and MCP server | Claude Code |
| 2026-01-26 | v4.1.0: Added viz-platform plugin and MCP server | Claude Code |
| 2026-01-25 | v4.0.0: Added data-platform plugin and MCP server | Claude Code |
| 2026-01-20 | v3.0.0: MCP servers moved to root with symlinks | Claude Code |
| 2026-01-20 | v3.0.0: Added clarity-assist, git-flow, pr-review plugins | Claude Code |
| 2026-01-20 | v3.0.0: Added docs/CONFIGURATION.md | Claude Code |
| 2026-01-20 | v3.0.0: Renamed marketplace to leo-claude-mktplace | Claude Code |
| 2026-01-20 | Removed docs/references/ (obsolete planning docs) | Claude Code |
| 2026-01-19 | Added claude-md-integration.md path pattern | Claude Code |
| 2025-12-15 | Restructured: MCP servers bundled in plugins | Claude Code |
| 2025-12-12 | Initial creation | Claude Code |
Reference in New Issue View Git Blame Copy Permalink