diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f53305..adc6279 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## [4.1.3] - 2025-09-15 +## [4.1.4] - 2025-09-20 +### Added +- Comprehensive flag documentation integrated into `/sc:help` command +- All 25 SuperClaude framework flags now discoverable from help system +- Practical usage examples and flag priority rules + +### Fixed +- MCP incremental installation and auto-detection system +- Auto-detection of existing MCP servers from .claude.json and claude_desktop_config.json +- Smart server merging (existing + selected + previously installed) +- Documentation cleanup: removed non-existent commands (sc:fix, sc:simple-pix, sc:update, sc:develop, sc:modernize, sc:simple-fix) +- CLI logic to allow mcp_docs installation without server selection + ### Changed -- Version bump from 4.1.0 to 4.1.3 +- MCP component now supports true incremental installation +- mcp_docs component auto-detects and installs documentation for all detected servers +- Improved error handling and graceful fallback for corrupted config files +- Enhanced user experience with single-source reference for all SuperClaude capabilities ## [4.1.0] - 2025-09-13 ### Added diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 1f8d100..1998ab1 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -518,7 +518,7 @@ This code of conduct draws inspiration from several established community standa **Last Updated**: December 2024 (SuperClaude Framework v4.0) **Next Review**: June 2025 (Semi-annual review cycle) -**Version**: 4.1.3 (Updated for v4 community structure and governance) +**Version**: 4.1.4 (Updated for v4 community structure and governance) **Review Schedule:** - **Semi-Annual Reviews**: Policy effectiveness assessment and community feedback integration diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 347de70..06926d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ SuperClaude Framework transforms Claude Code into a structured development platf **Good Bug Report Example:** ``` **Environment:** -- SuperClaude: 4.1.3 +- SuperClaude: 4.1.4 - OS: Ubuntu 22.04 - Claude Code: 1.5.2 - Python: 3.9.7 diff --git a/Docs/Getting-Started/installation.md b/Docs/Getting-Started/installation.md index 0d442c2..1b0e5f8 100644 --- a/Docs/Getting-Started/installation.md +++ b/Docs/Getting-Started/installation.md @@ -5,7 +5,7 @@ ### **Transform Claude Code with 21 Commands, 14 Agents & 6 MCP Servers**

- Version + Version Python Platform

@@ -266,7 +266,7 @@ SuperClaude install --dry-run ```bash # Verify SuperClaude version python3 -m SuperClaude --version -# Expected: SuperClaude 4.1.3 +# Expected: SuperClaude 4.1.4 # List installed components SuperClaude install --list-components diff --git a/Docs/Getting-Started/quick-start.md b/Docs/Getting-Started/quick-start.md index df647c0..e573c14 100644 --- a/Docs/Getting-Started/quick-start.md +++ b/Docs/Getting-Started/quick-start.md @@ -6,7 +6,7 @@

Framework - Version + Version Quick Start

@@ -486,7 +486,7 @@ Create custom workflows

- SuperClaude v4.1.3 - Context Engineering for Claude Code + SuperClaude v4.1.4 - Context Engineering for Claude Code

\ No newline at end of file diff --git a/Docs/Reference/common-issues.md b/Docs/Reference/common-issues.md index 15db1bc..396579a 100644 --- a/Docs/Reference/common-issues.md +++ b/Docs/Reference/common-issues.md @@ -13,7 +13,7 @@ Test: /sc:brainstorm "test" should ask questions ### 2. Installation Verification ```bash -python3 -m SuperClaude --version # Should show 4.1.3 +python3 -m SuperClaude --version # Should show 4.1.4 # If not working: # For pipx users @@ -71,7 +71,7 @@ pip3 install SuperClaude ``` ## Verification Checklist -- [ ] `python3 -m SuperClaude --version` returns 4.1.3 +- [ ] `python3 -m SuperClaude --version` returns 4.1.4 - [ ] `/sc:brainstorm "test"` works in Claude Code - [ ] `SuperClaude install --list-components` shows components diff --git a/Docs/Reference/troubleshooting.md b/Docs/Reference/troubleshooting.md index 83dbad7..d70ed5e 100644 --- a/Docs/Reference/troubleshooting.md +++ b/Docs/Reference/troubleshooting.md @@ -6,7 +6,7 @@ Quick fixes to advanced diagnostics for SuperClaude Framework issues. **Installation Verification:** ```bash -python3 -m SuperClaude --version # Should show 4.1.3 +python3 -m SuperClaude --version # Should show 4.1.4 SuperClaude install --list-components ``` @@ -19,7 +19,7 @@ SuperClaude install --list-components ``` **Resolution Checklist:** -- [ ] Version commands work and show 4.1.3 +- [ ] Version commands work and show 4.1.4 - [ ] `/sc:` commands respond in Claude Code - [ ] MCP servers listed: `SuperClaude install --list-components | grep mcp` diff --git a/Docs/User-Guide-jp/commands.md b/Docs/User-Guide-jp/commands.md index f020fcb..cf9d469 100644 --- a/Docs/User-Guide-jp/commands.md +++ b/Docs/User-Guide-jp/commands.md @@ -92,7 +92,7 @@ SuperClaude は、Claude Code が特殊な動作を実行するために読み ```shell # Verify SuperClaude is working (primary method) python3 -m SuperClaude --version -# Example output: SuperClaude 4.1.3 +# Example output: SuperClaude 4.1.4 # Claude Code CLI version check claude --version diff --git a/Docs/User-Guide-jp/modes.md b/Docs/User-Guide-jp/modes.md index 213025d..4e48c9a 100644 --- a/Docs/User-Guide-jp/modes.md +++ b/Docs/User-Guide-jp/modes.md @@ -358,10 +358,10 @@ Standard Approach: Consistent, professional baseline for all tasks /sc:implement "user login" --brainstorm # Add reasoning transparency to debugging -/sc:fix auth-issue --introspect +# 認証問題を透明な推理でデバッグ # Enable task management for simple operations -/sc:update styles.css --task-manage +# システマチックなタスク管理でスタイルファイルを更新 ``` ### モードの境界と優先順位 @@ -407,7 +407,7 @@ Standard Approach: Consistent, professional baseline for all tasks → 🎯 Phase coordination with quality gates # Phase 3: Implementation (Orchestration Mode coordinates tools) -/sc:develop frontend + backend +/sc:implement "frontend and backend systems" → 🎯 Magic (UI) + Context7 (patterns) + Sequential (architecture) → ⚡ Parallel execution optimization ``` @@ -422,7 +422,7 @@ Standard Approach: Consistent, professional baseline for all tasks → 💡 Pattern recognition across similar issues # Systematic resolution (Task Management coordinates) -/sc:fix auth-system --comprehensive +# 認証システムを包括的に修正 → 📋 Phase 1: Root cause analysis → 📋 Phase 2: Solution implementation → 📋 Phase 3: Testing and validation @@ -436,7 +436,7 @@ Standard Approach: Consistent, professional baseline for all tasks ```shell # Large refactoring with multiple constraints -/sc:modernize legacy-system/ --introspect --uc --orchestrate +/sc:improve legacy-system/ --introspect --uc --orchestrate → 🔍 Transparent reasoning (Introspection) → ⚡ Compressed communication (Token Efficiency) → 🎯 Optimal tool coordination (Orchestration) @@ -529,7 +529,7 @@ Standard Approach: Consistent, professional baseline for all tasks # Problem: Simple tasks getting complex coordination # Quick Fix: Reduce scope or use simpler commands /sc:implement "function" --no-task-manage # Disable coordination -/sc:simple-fix bug.js # Use basic commands +/sc:troubleshoot bug.js # Use basic commands # Check if task really is complex (>3 files, >2 directories) ``` diff --git a/Docs/User-Guide-zh/commands.md b/Docs/User-Guide-zh/commands.md index 35a684b..782088a 100644 --- a/Docs/User-Guide-zh/commands.md +++ b/Docs/User-Guide-zh/commands.md @@ -67,7 +67,7 @@ SuperClaude 提供行为上下文文件，Claude Code 通过读取这些文件 ```bash # 验证 SuperClaude 是否正常工作（主要方法） python3 -m SuperClaude --version -# 示例输出：SuperClaude 4.1.3 +# 示例输出：SuperClaude 4.1.4 # Claude Code CLI 版本检查 claude --version diff --git a/Docs/User-Guide-zh/modes.md b/Docs/User-Guide-zh/modes.md index 4eccb0b..3e915d3 100644 --- a/Docs/User-Guide-zh/modes.md +++ b/Docs/User-Guide-zh/modes.md @@ -297,10 +297,10 @@ Standard Approach: Consistent, professional baseline for all tasks /sc:implement "user login" --brainstorm # 为调试添加推理透明度 -/sc:fix auth-issue --introspect +# 使用透明推理调试认证问题 # 为简单操作启用任务管理 -/sc:update styles.css --task-manage +# 系统化任务管理更新样式文件 ``` ### 模式边界和优先级 @@ -337,7 +337,7 @@ Standard Approach: Consistent, professional baseline for all tasks → 🎯 带质量门控的阶段协调 # 阶段 3：实现（编排模式协调工具） -/sc:develop frontend + backend +/sc:implement "frontend and backend systems" → 🎯 Magic (UI) + Context7 (模式) + Sequential (架构) → ⚡ 并行执行优化 ``` @@ -351,7 +351,7 @@ Standard Approach: Consistent, professional baseline for all tasks → 💡 跨相似问题的模式识别 # 系统性解决（任务管理协调） -/sc:fix auth-system --comprehensive +# 全面修复认证系统 → 📋 阶段 1：根因分析 → 📋 阶段 2：解决方案实现 → 📋 阶段 3：测试和验证 @@ -362,7 +362,7 @@ Standard Approach: Consistent, professional baseline for all tasks **高复杂度场景：** ```bash # 带多重约束的大型重构 -/sc:modernize legacy-system/ --introspect --uc --orchestrate +/sc:improve legacy-system/ --introspect --uc --orchestrate → 🔍 透明推理introspect（内省） → ⚡ 压缩通信uc（令牌效率） → 🎯 最优工具协调orchestrate（编排） @@ -436,7 +436,7 @@ Standard Approach: Consistent, professional baseline for all tasks # 问题：简单任务得到复杂协调 # 快速修复：减少范围或使用更简单的命令 /sc:implement "function" --no-task-manage # 禁用协调 -/sc:simple-fix bug.js # 使用基本命令 +/sc:troubleshoot bug.js # 使用基本命令 # 检查任务是否真正复杂（>3 文件，>2 目录） ``` diff --git a/Docs/User-Guide/commands.md b/Docs/User-Guide/commands.md index d5330e3..4f62ded 100644 --- a/Docs/User-Guide/commands.md +++ b/Docs/User-Guide/commands.md @@ -67,7 +67,7 @@ SuperClaude provides behavioral context files that Claude Code reads to adopt sp ```bash # Verify SuperClaude is working (primary method) python3 -m SuperClaude --version -# Example output: SuperClaude 4.1.3 +# Example output: SuperClaude 4.1.4 # Claude Code CLI version check claude --version diff --git a/Docs/User-Guide/modes.md b/Docs/User-Guide/modes.md index 9cd3b7f..f33dd0a 100644 --- a/Docs/User-Guide/modes.md +++ b/Docs/User-Guide/modes.md @@ -298,10 +298,10 @@ Standard Approach: Consistent, professional baseline for all tasks /sc:implement "user login" --brainstorm # Add reasoning transparency to debugging -/sc:fix auth-issue --introspect +# Debug authentication issue with transparent reasoning # Enable task management for simple operations -/sc:update styles.css --task-manage +# Update styles.css with systematic task management ``` ### Mode Boundaries and Priority @@ -338,7 +338,7 @@ Standard Approach: Consistent, professional baseline for all tasks → 🎯 Phase coordination with quality gates # Phase 3: Implementation (Orchestration Mode coordinates tools) -/sc:develop frontend + backend +/sc:implement "frontend and backend systems" → 🎯 Magic (UI) + Context7 (patterns) + Sequential (architecture) → ⚡ Parallel execution optimization ``` @@ -352,7 +352,7 @@ Standard Approach: Consistent, professional baseline for all tasks → 💡 Pattern recognition across similar issues # Systematic resolution (Task Management coordinates) -/sc:fix auth-system --comprehensive +# Fix authentication system comprehensively → 📋 Phase 1: Root cause analysis → 📋 Phase 2: Solution implementation → 📋 Phase 3: Testing and validation @@ -363,7 +363,7 @@ Standard Approach: Consistent, professional baseline for all tasks **High-Complexity Scenarios:** ```bash # Large refactoring with multiple constraints -/sc:modernize legacy-system/ --introspect --uc --orchestrate +/sc:improve legacy-system/ --introspect --uc --orchestrate → 🔍 Transparent reasoning (Introspection) → ⚡ Compressed communication (Token Efficiency) → 🎯 Optimal tool coordination (Orchestration) @@ -437,7 +437,7 @@ For troubleshooting help, see: # Problem: Simple tasks getting complex coordination # Quick Fix: Reduce scope or use simpler commands /sc:implement "function" --no-task-manage # Disable coordination -/sc:simple-fix bug.js # Use basic commands +/sc:troubleshoot bug.js # Use basic commands # Check if task really is complex (>3 files, >2 directories) ``` diff --git a/README-ja.md b/README-ja.md index 9734d4c..3c4f459 100644 --- a/README-ja.md +++ b/README-ja.md @@ -5,7 +5,7 @@ ### **Claude Codeを構造化開発プラットフォームに変換**

- Version + Version License PRs Welcome

diff --git a/README-zh.md b/README-zh.md index 21a8384..d91c1dc 100644 --- a/README-zh.md +++ b/README-zh.md @@ -5,7 +5,7 @@ ### **将Claude Code转换为结构化开发平台**

- Version + Version License PRs Welcome

diff --git a/README.md b/README.md index 957f3d6..e9c2425 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Try SuperQwen Framework - Version + Version License PRs Welcome

diff --git a/SECURITY.md b/SECURITY.md index 4f499b3..bea6eb5 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -723,7 +723,7 @@ For organizations requiring dedicated security support: **Last Updated**: December 2024 (SuperClaude Framework v4.0) **Next Review**: March 2025 (Quarterly review cycle) -**Version**: 4.1.3 (Updated for v4 architectural changes) +**Version**: 4.1.4 (Updated for v4 architectural changes) **Review Schedule:** - **Quarterly Reviews**: Security policy accuracy and completeness assessment diff --git a/SuperClaude/Commands/help.md b/SuperClaude/Commands/help.md index 3977fcb..cd8b31e 100644 --- a/SuperClaude/Commands/help.md +++ b/SuperClaude/Commands/help.md @@ -51,12 +51,92 @@ Here is a complete list of all available SuperClaude (`/sc`) commands. | `/sc:troubleshoot` | Diagnose and resolve issues in code, builds, deployments, and system behavior | | `/sc:workflow` | Generate structured implementation workflows from PRDs and feature requirements | +## SuperClaude Framework Flags + +SuperClaude supports behavioral flags to enable specific execution modes and tool selection patterns. Use these flags with any `/sc` command to customize behavior. + +### Mode Activation Flags + +| Flag | Trigger | Behavior | +|------|---------|----------| +| `--brainstorm` | Vague project requests, exploration keywords | Activate collaborative discovery mindset, ask probing questions | +| `--introspect` | Self-analysis requests, error recovery | Expose thinking process with transparency markers | +| `--task-manage` | Multi-step operations (>3 steps) | Orchestrate through delegation, systematic organization | +| `--orchestrate` | Multi-tool operations, parallel execution | Optimize tool selection matrix, enable parallel thinking | +| `--token-efficient` | Context usage >75%, large-scale operations | Symbol-enhanced communication, 30-50% token reduction | + +### MCP Server Flags + +| Flag | Trigger | Behavior | +|------|---------|----------| +| `--c7` / `--context7` | Library imports, framework questions | Enable Context7 for curated documentation lookup | +| `--seq` / `--sequential` | Complex debugging, system design | Enable Sequential for structured multi-step reasoning | +| `--magic` | UI component requests (/ui, /21) | Enable Magic for modern UI generation from 21st.dev | +| `--morph` / `--morphllm` | Bulk code transformations | Enable Morphllm for efficient multi-file pattern application | +| `--serena` | Symbol operations, project memory | Enable Serena for semantic understanding and session persistence | +| `--play` / `--playwright` | Browser testing, E2E scenarios | Enable Playwright for real browser automation and testing | +| `--all-mcp` | Maximum complexity scenarios | Enable all MCP servers for comprehensive capability | +| `--no-mcp` | Native-only execution needs | Disable all MCP servers, use native tools | + +### Analysis Depth Flags + +| Flag | Trigger | Behavior | +|------|---------|----------| +| `--think` | Multi-component analysis needs | Standard structured analysis (~4K tokens), enables Sequential | +| `--think-hard` | Architectural analysis, system-wide dependencies | Deep analysis (~10K tokens), enables Sequential + Context7 | +| `--ultrathink` | Critical system redesign, legacy modernization | Maximum depth analysis (~32K tokens), enables all MCP servers | + +### Execution Control Flags + +| Flag | Trigger | Behavior | +|------|---------|----------| +| `--delegate [auto\|files\|folders]` | >7 directories OR >50 files | Enable sub-agent parallel processing with intelligent routing | +| `--concurrency [n]` | Resource optimization needs | Control max concurrent operations (range: 1-15) | +| `--loop` | Improvement keywords (polish, refine, enhance) | Enable iterative improvement cycles with validation gates | +| `--iterations [n]` | Specific improvement cycle requirements | Set improvement cycle count (range: 1-10) | +| `--validate` | Risk score >0.7, resource usage >75% | Pre-execution risk assessment and validation gates | +| `--safe-mode` | Resource usage >85%, production environment | Maximum validation, conservative execution | + +### Output Optimization Flags + +| Flag | Trigger | Behavior | +|------|---------|----------| +| `--uc` / `--ultracompressed` | Context pressure, efficiency requirements | Symbol communication system, 30-50% token reduction | +| `--scope [file\|module\|project\|system]` | Analysis boundary needs | Define operational scope and analysis depth | +| `--focus [performance\|security\|quality\|architecture\|accessibility\|testing]` | Domain-specific optimization | Target specific analysis domain and expertise application | + +### Flag Priority Rules + +- **Safety First**: `--safe-mode` > `--validate` > optimization flags +- **Explicit Override**: User flags > auto-detection +- **Depth Hierarchy**: `--ultrathink` > `--think-hard` > `--think` +- **MCP Control**: `--no-mcp` overrides all individual MCP flags +- **Scope Precedence**: system > project > module > file + +### Usage Examples + +```bash +# Deep analysis with Context7 enabled +/sc:analyze --think-hard --context7 src/ + +# UI development with Magic and validation +/sc:implement --magic --validate "Add user dashboard" + +# Token-efficient task management +/sc:task --token-efficient --delegate auto "Refactor authentication system" + +# Safe production deployment +/sc:build --safe-mode --validate --focus security +``` + ## Boundaries **Will:** - Display comprehensive list of available SuperClaude commands - Provide clear descriptions of each command's functionality - Present information in readable tabular format +- Show all available SuperClaude framework flags and their usage +- Provide flag usage examples and priority rules **Will Not:** - Execute any commands or create any files diff --git a/SuperClaude/Core/RULES.md b/SuperClaude/Core/RULES.md index a56cb91..ea1365d 100644 --- a/SuperClaude/Core/RULES.md +++ b/SuperClaude/Core/RULES.md @@ -1,258 +1,258 @@ -# Claude Code Behavioral Rules - -Actionable rules for enhanced Claude Code framework operation. - -## Rule Priority System - -**🔴 CRITICAL**: Security, data safety, production breaks - Never compromise -**🟡 IMPORTANT**: Quality, maintainability, professionalism - Strong preference -**🟢 RECOMMENDED**: Optimization, style, best practices - Apply when practical - -### Conflict Resolution Hierarchy -1. **Safety First**: Security/data rules always win -2. **Scope > Features**: Build only what's asked > complete everything -3. **Quality > Speed**: Except in genuine emergencies -4. **Context Matters**: Prototype vs Production requirements differ - -## Workflow Rules -**Priority**: 🟡 **Triggers**: All development tasks - -- **Task Pattern**: Understand → Plan (with parallelization analysis) → TodoWrite(3+ tasks) → Execute → Track → Validate -- **Batch Operations**: ALWAYS parallel tool calls by default, sequential ONLY for dependencies -- **Validation Gates**: Always validate before execution, verify after completion -- **Quality Checks**: Run lint/typecheck before marking tasks complete -- **Context Retention**: Maintain ≥90% understanding across operations -- **Evidence-Based**: All claims must be verifiable through testing or documentation -- **Discovery First**: Complete project-wide analysis before systematic changes -- **Session Lifecycle**: Initialize with /sc:load, checkpoint regularly, save before end -- **Session Pattern**: /sc:load → Work → Checkpoint (30min) → /sc:save -- **Checkpoint Triggers**: Task completion, 30-min intervals, risky operations - -✅ **Right**: Plan → TodoWrite → Execute → Validate -❌ **Wrong**: Jump directly to implementation without planning - -## Planning Efficiency -**Priority**: 🔴 **Triggers**: All planning phases, TodoWrite operations, multi-step tasks - -- **Parallelization Analysis**: During planning, explicitly identify operations that can run concurrently -- **Tool Optimization Planning**: Plan for optimal MCP server combinations and batch operations -- **Dependency Mapping**: Clearly separate sequential dependencies from parallelizable tasks -- **Resource Estimation**: Consider token usage and execution time during planning phase -- **Efficiency Metrics**: Plan should specify expected parallelization gains (e.g., "3 parallel ops = 60% time saving") - -✅ **Right**: "Plan: 1) Parallel: [Read 5 files] 2) Sequential: analyze → 3) Parallel: [Edit all files]" -❌ **Wrong**: "Plan: Read file1 → Read file2 → Read file3 → analyze → edit file1 → edit file2" - -## Implementation Completeness -**Priority**: 🟡 **Triggers**: Creating features, writing functions, code generation - -- **No Partial Features**: If you start implementing, you MUST complete to working state -- **No TODO Comments**: Never leave TODO for core functionality or implementations -- **No Mock Objects**: No placeholders, fake data, or stub implementations -- **No Incomplete Functions**: Every function must work as specified, not throw "not implemented" -- **Completion Mindset**: "Start it = Finish it" - no exceptions for feature delivery -- **Real Code Only**: All generated code must be production-ready, not scaffolding - -✅ **Right**: `function calculate() { return price * tax; }` -❌ **Wrong**: `function calculate() { throw new Error("Not implemented"); }` -❌ **Wrong**: `// TODO: implement tax calculation` - -## Scope Discipline -**Priority**: 🟡 **Triggers**: Vague requirements, feature expansion, architecture decisions - -- **Build ONLY What's Asked**: No adding features beyond explicit requirements -- **MVP First**: Start with minimum viable solution, iterate based on feedback -- **No Enterprise Bloat**: No auth, deployment, monitoring unless explicitly requested -- **Single Responsibility**: Each component does ONE thing well -- **Simple Solutions**: Prefer simple code that can evolve over complex architectures -- **Think Before Build**: Understand → Plan → Build, not Build → Build more -- **YAGNI Enforcement**: You Aren't Gonna Need It - no speculative features - -✅ **Right**: "Build login form" → Just login form -❌ **Wrong**: "Build login form" → Login + registration + password reset + 2FA - -## Code Organization -**Priority**: 🟢 **Triggers**: Creating files, structuring projects, naming decisions - -- **Naming Convention Consistency**: Follow language/framework standards (camelCase for JS, snake_case for Python) -- **Descriptive Names**: Files, functions, variables must clearly describe their purpose -- **Logical Directory Structure**: Organize by feature/domain, not file type -- **Pattern Following**: Match existing project organization and naming schemes -- **Hierarchical Logic**: Create clear parent-child relationships in folder structure -- **No Mixed Conventions**: Never mix camelCase/snake_case/kebab-case within same project -- **Elegant Organization**: Clean, scalable structure that aids navigation and understanding - -✅ **Right**: `getUserData()`, `user_data.py`, `components/auth/` -❌ **Wrong**: `get_userData()`, `userdata.py`, `files/everything/` - -## Workspace Hygiene -**Priority**: 🟡 **Triggers**: After operations, session end, temporary file creation - -- **Clean After Operations**: Remove temporary files, scripts, and directories when done -- **No Artifact Pollution**: Delete build artifacts, logs, and debugging outputs -- **Temporary File Management**: Clean up all temporary files before task completion -- **Professional Workspace**: Maintain clean project structure without clutter -- **Session End Cleanup**: Remove any temporary resources before ending session -- **Version Control Hygiene**: Never leave temporary files that could be accidentally committed -- **Resource Management**: Delete unused directories and files to prevent workspace bloat - -✅ **Right**: `rm temp_script.py` after use -❌ **Wrong**: Leaving `debug.sh`, `test.log`, `temp/` directories - -## Failure Investigation -**Priority**: 🔴 **Triggers**: Errors, test failures, unexpected behavior, tool failures - -- **Root Cause Analysis**: Always investigate WHY failures occur, not just that they failed -- **Never Skip Tests**: Never disable, comment out, or skip tests to achieve results -- **Never Skip Validation**: Never bypass quality checks or validation to make things work -- **Debug Systematically**: Step back, assess error messages, investigate tool failures thoroughly -- **Fix Don't Workaround**: Address underlying issues, not just symptoms -- **Tool Failure Investigation**: When MCP tools or scripts fail, debug before switching approaches -- **Quality Integrity**: Never compromise system integrity to achieve short-term results -- **Methodical Problem-Solving**: Understand → Diagnose → Fix → Verify, don't rush to solutions - -✅ **Right**: Analyze stack trace → identify root cause → fix properly -❌ **Wrong**: Comment out failing test to make build pass -**Detection**: `grep -r "skip\|disable\|TODO" tests/` - -## Professional Honesty -**Priority**: 🟡 **Triggers**: Assessments, reviews, recommendations, technical claims - -- **No Marketing Language**: Never use "blazingly fast", "100% secure", "magnificent", "excellent" -- **No Fake Metrics**: Never invent time estimates, percentages, or ratings without evidence -- **Critical Assessment**: Provide honest trade-offs and potential issues with approaches -- **Push Back When Needed**: Point out problems with proposed solutions respectfully -- **Evidence-Based Claims**: All technical claims must be verifiable, not speculation -- **No Sycophantic Behavior**: Stop over-praising, provide professional feedback instead -- **Realistic Assessments**: State "untested", "MVP", "needs validation" - not "production-ready" -- **Professional Language**: Use technical terms, avoid sales/marketing superlatives - -✅ **Right**: "This approach has trade-offs: faster but uses more memory" -❌ **Wrong**: "This magnificent solution is blazingly fast and 100% secure!" - -## Git Workflow -**Priority**: 🔴 **Triggers**: Session start, before changes, risky operations - -- **Always Check Status First**: Start every session with `git status` and `git branch` -- **Feature Branches Only**: Create feature branches for ALL work, never work on main/master -- **Incremental Commits**: Commit frequently with meaningful messages, not giant commits -- **Verify Before Commit**: Always `git diff` to review changes before staging -- **Create Restore Points**: Commit before risky operations for easy rollback -- **Branch for Experiments**: Use branches to safely test different approaches -- **Clean History**: Use descriptive commit messages, avoid "fix", "update", "changes" -- **Non-Destructive Workflow**: Always preserve ability to rollback changes - -✅ **Right**: `git checkout -b feature/auth` → work → commit → PR -❌ **Wrong**: Work directly on main/master branch -**Detection**: `git branch` should show feature branch, not main/master - -## Tool Optimization -**Priority**: 🟢 **Triggers**: Multi-step operations, performance needs, complex tasks - -- **Best Tool Selection**: Always use the most powerful tool for each task (MCP > Native > Basic) -- **Parallel Everything**: Execute independent operations in parallel, never sequentially -- **Agent Delegation**: Use Task agents for complex multi-step operations (>3 steps) -- **MCP Server Usage**: Leverage specialized MCP servers for their strengths (morphllm for bulk edits, sequential-thinking for analysis) -- **Batch Operations**: Use MultiEdit over multiple Edits, batch Read calls, group operations -- **Powerful Search**: Use Grep tool over bash grep, Glob over find, specialized search tools -- **Efficiency First**: Choose speed and power over familiarity - use the fastest method available -- **Tool Specialization**: Match tools to their designed purpose (e.g., playwright for web, context7 for docs) - -✅ **Right**: Use MultiEdit for 3+ file changes, parallel Read calls -❌ **Wrong**: Sequential Edit calls, bash grep instead of Grep tool - -## File Organization -**Priority**: 🟡 **Triggers**: File creation, project structuring, documentation - -- **Think Before Write**: Always consider WHERE to place files before creating them -- **Claude-Specific Documentation**: Put reports, analyses, summaries in `claudedocs/` directory -- **Test Organization**: Place all tests in `tests/`, `__tests__/`, or `test/` directories -- **Script Organization**: Place utility scripts in `scripts/`, `tools/`, or `bin/` directories -- **Check Existing Patterns**: Look for existing test/script directories before creating new ones -- **No Scattered Tests**: Never create test_*.py or *.test.js next to source files -- **No Random Scripts**: Never create debug.sh, script.py, utility.js in random locations -- **Separation of Concerns**: Keep tests, scripts, docs, and source code properly separated -- **Purpose-Based Organization**: Organize files by their intended function and audience - -✅ **Right**: `tests/auth.test.js`, `scripts/deploy.sh`, `claudedocs/analysis.md` -❌ **Wrong**: `auth.test.js` next to `auth.js`, `debug.sh` in project root - -## Safety Rules -**Priority**: 🔴 **Triggers**: File operations, library usage, codebase changes - -- **Framework Respect**: Check package.json/deps before using libraries -- **Pattern Adherence**: Follow existing project conventions and import styles -- **Transaction-Safe**: Prefer batch operations with rollback capability -- **Systematic Changes**: Plan → Execute → Verify for codebase modifications - -✅ **Right**: Check dependencies → follow patterns → execute safely -❌ **Wrong**: Ignore existing conventions, make unplanned changes - -## Temporal Awareness -**Priority**: 🔴 **Triggers**: Date/time references, version checks, deadline calculations, "latest" keywords - -- **Always Verify Current Date**: Check context for "Today's date" before ANY temporal assessment -- **Never Assume From Knowledge Cutoff**: Don't default to January 2025 or knowledge cutoff dates -- **Explicit Time References**: Always state the source of date/time information -- **Version Context**: When discussing "latest" versions, always verify against current date -- **Temporal Calculations**: Base all time math on verified current date, not assumptions - -✅ **Right**: "Checking env: Today is 2025-08-15, so the Q3 deadline is..." -❌ **Wrong**: "Since it's January 2025..." (without checking) -**Detection**: Any date reference without prior env verification - - -## Quick Reference & Decision Trees - -### Critical Decision Flows - -**🔴 Before Any File Operations** -``` -File operation needed? -├─ Writing/Editing? → Read existing first → Understand patterns → Edit -├─ Creating new? → Check existing structure → Place appropriately -└─ Safety check → Absolute paths only → No auto-commit -``` - -**🟡 Starting New Feature** -``` -New feature request? -├─ Scope clear? → No → Brainstorm mode first -├─ >3 steps? → Yes → TodoWrite required -├─ Patterns exist? → Yes → Follow exactly -├─ Tests available? → Yes → Run before starting -└─ Framework deps? → Check package.json first -``` - -**🟢 Tool Selection Matrix** -``` -Task type → Best tool: -├─ Multi-file edits → MultiEdit > individual Edits -├─ Complex analysis → Task agent > native reasoning -├─ Code search → Grep > bash grep -├─ UI components → Magic MCP > manual coding -├─ Documentation → Context7 MCP > web search -└─ Browser testing → Playwright MCP > unit tests -``` - -### Priority-Based Quick Actions - -#### 🔴 CRITICAL (Never Compromise) -- `git status && git branch` before starting -- Read before Write/Edit operations -- Feature branches only, never main/master -- Root cause analysis, never skip validation -- Absolute paths, no auto-commit - -#### 🟡 IMPORTANT (Strong Preference) -- TodoWrite for >3 step tasks -- Complete all started implementations -- Build only what's asked (MVP first) -- Professional language (no marketing superlatives) -- Clean workspace (remove temp files) - -#### 🟢 RECOMMENDED (Apply When Practical) -- Parallel operations over sequential -- Descriptive naming conventions -- MCP tools over basic alternatives +# Claude Code Behavioral Rules + +Actionable rules for enhanced Claude Code framework operation. + +## Rule Priority System + +**🔴 CRITICAL**: Security, data safety, production breaks - Never compromise +**🟡 IMPORTANT**: Quality, maintainability, professionalism - Strong preference +**🟢 RECOMMENDED**: Optimization, style, best practices - Apply when practical + +### Conflict Resolution Hierarchy +1. **Safety First**: Security/data rules always win +2. **Scope > Features**: Build only what's asked > complete everything +3. **Quality > Speed**: Except in genuine emergencies +4. **Context Matters**: Prototype vs Production requirements differ + +## Workflow Rules +**Priority**: 🟡 **Triggers**: All development tasks + +- **Task Pattern**: Understand → Plan (with parallelization analysis) → TodoWrite(3+ tasks) → Execute → Track → Validate +- **Batch Operations**: ALWAYS parallel tool calls by default, sequential ONLY for dependencies +- **Validation Gates**: Always validate before execution, verify after completion +- **Quality Checks**: Run lint/typecheck before marking tasks complete +- **Context Retention**: Maintain ≥90% understanding across operations +- **Evidence-Based**: All claims must be verifiable through testing or documentation +- **Discovery First**: Complete project-wide analysis before systematic changes +- **Session Lifecycle**: Initialize with /sc:load, checkpoint regularly, save before end +- **Session Pattern**: /sc:load → Work → Checkpoint (30min) → /sc:save +- **Checkpoint Triggers**: Task completion, 30-min intervals, risky operations + +✅ **Right**: Plan → TodoWrite → Execute → Validate +❌ **Wrong**: Jump directly to implementation without planning + +## Planning Efficiency +**Priority**: 🔴 **Triggers**: All planning phases, TodoWrite operations, multi-step tasks + +- **Parallelization Analysis**: During planning, explicitly identify operations that can run concurrently +- **Tool Optimization Planning**: Plan for optimal MCP server combinations and batch operations +- **Dependency Mapping**: Clearly separate sequential dependencies from parallelizable tasks +- **Resource Estimation**: Consider token usage and execution time during planning phase +- **Efficiency Metrics**: Plan should specify expected parallelization gains (e.g., "3 parallel ops = 60% time saving") + +✅ **Right**: "Plan: 1) Parallel: [Read 5 files] 2) Sequential: analyze → 3) Parallel: [Edit all files]" +❌ **Wrong**: "Plan: Read file1 → Read file2 → Read file3 → analyze → edit file1 → edit file2" + +## Implementation Completeness +**Priority**: 🟡 **Triggers**: Creating features, writing functions, code generation + +- **No Partial Features**: If you start implementing, you MUST complete to working state +- **No TODO Comments**: Never leave TODO for core functionality or implementations +- **No Mock Objects**: No placeholders, fake data, or stub implementations +- **No Incomplete Functions**: Every function must work as specified, not throw "not implemented" +- **Completion Mindset**: "Start it = Finish it" - no exceptions for feature delivery +- **Real Code Only**: All generated code must be production-ready, not scaffolding + +✅ **Right**: `function calculate() { return price * tax; }` +❌ **Wrong**: `function calculate() { throw new Error("Not implemented"); }` +❌ **Wrong**: `// TODO: implement tax calculation` + +## Scope Discipline +**Priority**: 🟡 **Triggers**: Vague requirements, feature expansion, architecture decisions + +- **Build ONLY What's Asked**: No adding features beyond explicit requirements +- **MVP First**: Start with minimum viable solution, iterate based on feedback +- **No Enterprise Bloat**: No auth, deployment, monitoring unless explicitly requested +- **Single Responsibility**: Each component does ONE thing well +- **Simple Solutions**: Prefer simple code that can evolve over complex architectures +- **Think Before Build**: Understand → Plan → Build, not Build → Build more +- **YAGNI Enforcement**: You Aren't Gonna Need It - no speculative features + +✅ **Right**: "Build login form" → Just login form +❌ **Wrong**: "Build login form" → Login + registration + password reset + 2FA + +## Code Organization +**Priority**: 🟢 **Triggers**: Creating files, structuring projects, naming decisions + +- **Naming Convention Consistency**: Follow language/framework standards (camelCase for JS, snake_case for Python) +- **Descriptive Names**: Files, functions, variables must clearly describe their purpose +- **Logical Directory Structure**: Organize by feature/domain, not file type +- **Pattern Following**: Match existing project organization and naming schemes +- **Hierarchical Logic**: Create clear parent-child relationships in folder structure +- **No Mixed Conventions**: Never mix camelCase/snake_case/kebab-case within same project +- **Elegant Organization**: Clean, scalable structure that aids navigation and understanding + +✅ **Right**: `getUserData()`, `user_data.py`, `components/auth/` +❌ **Wrong**: `get_userData()`, `userdata.py`, `files/everything/` + +## Workspace Hygiene +**Priority**: 🟡 **Triggers**: After operations, session end, temporary file creation + +- **Clean After Operations**: Remove temporary files, scripts, and directories when done +- **No Artifact Pollution**: Delete build artifacts, logs, and debugging outputs +- **Temporary File Management**: Clean up all temporary files before task completion +- **Professional Workspace**: Maintain clean project structure without clutter +- **Session End Cleanup**: Remove any temporary resources before ending session +- **Version Control Hygiene**: Never leave temporary files that could be accidentally committed +- **Resource Management**: Delete unused directories and files to prevent workspace bloat + +✅ **Right**: `rm temp_script.py` after use +❌ **Wrong**: Leaving `debug.sh`, `test.log`, `temp/` directories + +## Failure Investigation +**Priority**: 🔴 **Triggers**: Errors, test failures, unexpected behavior, tool failures + +- **Root Cause Analysis**: Always investigate WHY failures occur, not just that they failed +- **Never Skip Tests**: Never disable, comment out, or skip tests to achieve results +- **Never Skip Validation**: Never bypass quality checks or validation to make things work +- **Debug Systematically**: Step back, assess error messages, investigate tool failures thoroughly +- **Fix Don't Workaround**: Address underlying issues, not just symptoms +- **Tool Failure Investigation**: When MCP tools or scripts fail, debug before switching approaches +- **Quality Integrity**: Never compromise system integrity to achieve short-term results +- **Methodical Problem-Solving**: Understand → Diagnose → Fix → Verify, don't rush to solutions + +✅ **Right**: Analyze stack trace → identify root cause → fix properly +❌ **Wrong**: Comment out failing test to make build pass +**Detection**: `grep -r "skip\|disable\|TODO" tests/` + +## Professional Honesty +**Priority**: 🟡 **Triggers**: Assessments, reviews, recommendations, technical claims + +- **No Marketing Language**: Never use "blazingly fast", "100% secure", "magnificent", "excellent" +- **No Fake Metrics**: Never invent time estimates, percentages, or ratings without evidence +- **Critical Assessment**: Provide honest trade-offs and potential issues with approaches +- **Push Back When Needed**: Point out problems with proposed solutions respectfully +- **Evidence-Based Claims**: All technical claims must be verifiable, not speculation +- **No Sycophantic Behavior**: Stop over-praising, provide professional feedback instead +- **Realistic Assessments**: State "untested", "MVP", "needs validation" - not "production-ready" +- **Professional Language**: Use technical terms, avoid sales/marketing superlatives + +✅ **Right**: "This approach has trade-offs: faster but uses more memory" +❌ **Wrong**: "This magnificent solution is blazingly fast and 100% secure!" + +## Git Workflow +**Priority**: 🔴 **Triggers**: Session start, before changes, risky operations + +- **Always Check Status First**: Start every session with `git status` and `git branch` +- **Feature Branches Only**: Create feature branches for ALL work, never work on main/master +- **Incremental Commits**: Commit frequently with meaningful messages, not giant commits +- **Verify Before Commit**: Always `git diff` to review changes before staging +- **Create Restore Points**: Commit before risky operations for easy rollback +- **Branch for Experiments**: Use branches to safely test different approaches +- **Clean History**: Use descriptive commit messages, avoid "fix", "update", "changes" +- **Non-Destructive Workflow**: Always preserve ability to rollback changes + +✅ **Right**: `git checkout -b feature/auth` → work → commit → PR +❌ **Wrong**: Work directly on main/master branch +**Detection**: `git branch` should show feature branch, not main/master + +## Tool Optimization +**Priority**: 🟢 **Triggers**: Multi-step operations, performance needs, complex tasks + +- **Best Tool Selection**: Always use the most powerful tool for each task (MCP > Native > Basic) +- **Parallel Everything**: Execute independent operations in parallel, never sequentially +- **Agent Delegation**: Use Task agents for complex multi-step operations (>3 steps) +- **MCP Server Usage**: Leverage specialized MCP servers for their strengths (morphllm for bulk edits, sequential-thinking for analysis) +- **Batch Operations**: Use MultiEdit over multiple Edits, batch Read calls, group operations +- **Powerful Search**: Use Grep tool over bash grep, Glob over find, specialized search tools +- **Efficiency First**: Choose speed and power over familiarity - use the fastest method available +- **Tool Specialization**: Match tools to their designed purpose (e.g., playwright for web, context7 for docs) + +✅ **Right**: Use MultiEdit for 3+ file changes, parallel Read calls +❌ **Wrong**: Sequential Edit calls, bash grep instead of Grep tool + +## File Organization +**Priority**: 🟡 **Triggers**: File creation, project structuring, documentation + +- **Think Before Write**: Always consider WHERE to place files before creating them +- **Claude-Specific Documentation**: Put reports, analyses, summaries in `claudedocs/` directory +- **Test Organization**: Place all tests in `tests/`, `__tests__/`, or `test/` directories +- **Script Organization**: Place utility scripts in `scripts/`, `tools/`, or `bin/` directories +- **Check Existing Patterns**: Look for existing test/script directories before creating new ones +- **No Scattered Tests**: Never create test_*.py or *.test.js next to source files +- **No Random Scripts**: Never create debug.sh, script.py, utility.js in random locations +- **Separation of Concerns**: Keep tests, scripts, docs, and source code properly separated +- **Purpose-Based Organization**: Organize files by their intended function and audience + +✅ **Right**: `tests/auth.test.js`, `scripts/deploy.sh`, `claudedocs/analysis.md` +❌ **Wrong**: `auth.test.js` next to `auth.js`, `debug.sh` in project root + +## Safety Rules +**Priority**: 🔴 **Triggers**: File operations, library usage, codebase changes + +- **Framework Respect**: Check package.json/deps before using libraries +- **Pattern Adherence**: Follow existing project conventions and import styles +- **Transaction-Safe**: Prefer batch operations with rollback capability +- **Systematic Changes**: Plan → Execute → Verify for codebase modifications + +✅ **Right**: Check dependencies → follow patterns → execute safely +❌ **Wrong**: Ignore existing conventions, make unplanned changes + +## Temporal Awareness +**Priority**: 🔴 **Triggers**: Date/time references, version checks, deadline calculations, "latest" keywords + +- **Always Verify Current Date**: Check context for "Today's date" before ANY temporal assessment +- **Never Assume From Knowledge Cutoff**: Don't default to January 2025 or knowledge cutoff dates +- **Explicit Time References**: Always state the source of date/time information +- **Version Context**: When discussing "latest" versions, always verify against current date +- **Temporal Calculations**: Base all time math on verified current date, not assumptions + +✅ **Right**: "Checking env: Today is 2025-08-15, so the Q3 deadline is..." +❌ **Wrong**: "Since it's January 2025..." (without checking) +**Detection**: Any date reference without prior env verification + + +## Quick Reference & Decision Trees + +### Critical Decision Flows + +**🔴 Before Any File Operations** +``` +File operation needed? +├─ Writing/Editing? → Read existing first → Understand patterns → Edit +├─ Creating new? → Check existing structure → Place appropriately +└─ Safety check → Absolute paths only → No auto-commit +``` + +**🟡 Starting New Feature** +``` +New feature request? +├─ Scope clear? → No → Brainstorm mode first +├─ >3 steps? → Yes → TodoWrite required +├─ Patterns exist? → Yes → Follow exactly +├─ Tests available? → Yes → Run before starting +└─ Framework deps? → Check package.json first +``` + +**🟢 Tool Selection Matrix** +``` +Task type → Best tool: +├─ Multi-file edits → MultiEdit > individual Edits +├─ Complex analysis → Task agent > native reasoning +├─ Code search → Grep > bash grep +├─ UI components → Magic MCP > manual coding +├─ Documentation → Context7 MCP > web search +└─ Browser testing → Playwright MCP > unit tests +``` + +### Priority-Based Quick Actions + +#### 🔴 CRITICAL (Never Compromise) +- `git status && git branch` before starting +- Read before Write/Edit operations +- Feature branches only, never main/master +- Root cause analysis, never skip validation +- Absolute paths, no auto-commit + +#### 🟡 IMPORTANT (Strong Preference) +- TodoWrite for >3 step tasks +- Complete all started implementations +- Build only what's asked (MVP first) +- Professional language (no marketing superlatives) +- Clean workspace (remove temp files) + +#### 🟢 RECOMMENDED (Apply When Practical) +- Parallel operations over sequential +- Descriptive naming conventions +- MCP tools over basic alternatives - Batch operations when possible \ No newline at end of file diff --git a/SuperClaude/__init__.py b/SuperClaude/__init__.py index d64558c..538035d 100644 --- a/SuperClaude/__init__.py +++ b/SuperClaude/__init__.py @@ -17,7 +17,7 @@ from pathlib import Path try: __version__ = (Path(__file__).parent.parent / "VERSION").read_text().strip() except Exception: - __version__ = "4.1.3" # Fallback + __version__ = "4.1.4" # Fallback __author__ = "NomenAK, Mithun Gowda B" __email__ = "anton.knoery@gmail.com, mithungowda.b7411@gmail.com" __github__ = "NomenAK, mithun50" diff --git a/VERSION b/VERSION index de197cc..a95f288 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -4.1.3 +4.1.4 diff --git a/package.json b/package.json index 92cc269..e83e1b5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@bifrost_inc/superclaude", - "version": "4.1.3", + "version": "4.1.4", "description": "SuperClaude Framework NPM wrapper - Official Node.js wrapper for the Python SuperClaude package. Enhances Claude Code with specialized commands and AI development tools.", "scripts": { "postinstall": "node ./bin/install.js", diff --git a/pyproject.toml b/pyproject.toml index 5fa8b8c..9bad9f8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,19 +4,20 @@ build-backend = "setuptools.build_meta" [project] name = "SuperClaude" -version = "4.1.3" +version = "4.1.4" authors = [ {name = "NomenAK", email = "anton.knoery@gmail.com"}, {name = "Mithun Gowda B", email = "mithungowda.b7411@gmail.com"} ] description = "SuperClaude Framework Management Hub - AI-enhanced development framework for Claude Code" readme = "README.md" -license = "MIT" +license = {text = "MIT"} requires-python = ">=3.8" classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", -"Operating System :: OS Independent", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", diff --git a/setup/__init__.py b/setup/__init__.py index 1d9aff0..cd8991a 100644 --- a/setup/__init__.py +++ b/setup/__init__.py @@ -8,7 +8,7 @@ from pathlib import Path try: __version__ = (Path(__file__).parent.parent / "VERSION").read_text().strip() except Exception: - __version__ = "4.1.3" # Fallback + __version__ = "4.1.4" # Fallback __author__ = "NomenAK, Mithun Gowda B" @@ -17,5 +17,8 @@ SETUP_DIR = Path(__file__).parent PROJECT_ROOT = SETUP_DIR.parent DATA_DIR = SETUP_DIR / "data" +# Import home directory detection for immutable distros +from .utils.paths import get_home_directory + # Installation target -DEFAULT_INSTALL_DIR = Path.home() / ".claude" \ No newline at end of file +DEFAULT_INSTALL_DIR = get_home_directory() / ".claude" \ No newline at end of file diff --git a/setup/cli/base.py b/setup/cli/base.py index 82b31ba..96f048b 100644 --- a/setup/cli/base.py +++ b/setup/cli/base.py @@ -10,7 +10,7 @@ from pathlib import Path try: __version__ = (Path(__file__).parent.parent.parent / "VERSION").read_text().strip() except Exception: - __version__ = "4.1.3" # Fallback + __version__ = "4.1.4" # Fallback def get_command_info(): diff --git a/setup/cli/commands/backup.py b/setup/cli/commands/backup.py index f145a43..fbca3d6 100644 --- a/setup/cli/commands/backup.py +++ b/setup/cli/commands/backup.py @@ -8,6 +8,7 @@ import time import tarfile import json from pathlib import Path +from ...utils.paths import get_home_directory from datetime import datetime from typing import List, Optional, Dict, Any, Tuple import argparse @@ -494,7 +495,7 @@ def run(args: argparse.Namespace) -> int: operation.setup_operation_logging(args) logger = get_logger() # ✅ Inserted validation code - expected_home = Path.home().resolve() + expected_home = get_home_directory().resolve() actual_dir = args.install_dir.resolve() if not str(actual_dir).startswith(str(expected_home)): diff --git a/setup/cli/commands/install.py b/setup/cli/commands/install.py index 622ed88..ed6e0a8 100644 --- a/setup/cli/commands/install.py +++ b/setup/cli/commands/install.py @@ -6,6 +6,7 @@ Refactored from install.py for unified CLI hub import sys import time from pathlib import Path +from ...utils.paths import get_home_directory from typing import List, Optional, Dict, Any import argparse @@ -125,16 +126,28 @@ def get_components_to_install(args: argparse.Namespace, registry: ComponentRegis else: components = args.components - # If mcp is specified non-interactively, we should still ask which servers to install. - if 'mcp' in components: + # If mcp or mcp_docs is specified non-interactively, we should still ask which servers to install. + if 'mcp' in components or 'mcp_docs' in components: selected_servers = select_mcp_servers(registry) if not hasattr(config_manager, '_installation_context'): config_manager._installation_context = {} config_manager._installation_context["selected_mcp_servers"] = selected_servers - # If the user selected some servers, but didn't select mcp_docs, add it. - if selected_servers and 'mcp_docs' not in components: - components.append('mcp_docs') + # If the user selected some servers, ensure both mcp and mcp_docs are included + if selected_servers: + if 'mcp' not in components: + components.append('mcp') + logger.debug(f"Auto-added 'mcp' component for selected servers: {selected_servers}") + if 'mcp_docs' not in components: + components.append('mcp_docs') + logger.debug(f"Auto-added 'mcp_docs' component for selected servers: {selected_servers}") + + logger.info(f"Final components to install: {components}") + + # If mcp_docs was explicitly requested but no servers selected, allow auto-detection + elif not selected_servers and 'mcp_docs' in components: + logger.info("mcp_docs component will auto-detect existing MCP servers") + logger.info("Documentation will be installed for any detected servers") return components @@ -187,7 +200,7 @@ def select_mcp_servers(registry: ComponentRegistry) -> List[str]: try: # Get MCP component to access server list - mcp_instance = registry.get_component_instance("mcp", Path.home() / ".claude") + mcp_instance = registry.get_component_instance("mcp", get_home_directory() / ".claude") if not mcp_instance or not hasattr(mcp_instance, 'mcp_servers'): logger.error("Could not access MCP server information") return [] @@ -526,7 +539,7 @@ def run(args: argparse.Namespace) -> int: operation.setup_operation_logging(args) logger = get_logger() # ✅ Enhanced security validation with symlink protection - expected_home = Path.home().resolve() + expected_home = get_home_directory().resolve() install_dir_original = args.install_dir install_dir_resolved = args.install_dir.resolve() diff --git a/setup/cli/commands/uninstall.py b/setup/cli/commands/uninstall.py index cc509b7..84d760a 100644 --- a/setup/cli/commands/uninstall.py +++ b/setup/cli/commands/uninstall.py @@ -6,6 +6,7 @@ Refactored from uninstall.py for unified CLI hub import sys import time from pathlib import Path +from ...utils.paths import get_home_directory from typing import List, Optional, Dict, Any import argparse @@ -766,7 +767,7 @@ def run(args: argparse.Namespace) -> int: operation.setup_operation_logging(args) logger = get_logger() # ✅ Inserted validation code - expected_home = Path.home().resolve() + expected_home = get_home_directory().resolve() actual_dir = args.install_dir.resolve() if not str(actual_dir).startswith(str(expected_home)): diff --git a/setup/cli/commands/update.py b/setup/cli/commands/update.py index fd0a892..d04521d 100644 --- a/setup/cli/commands/update.py +++ b/setup/cli/commands/update.py @@ -6,6 +6,7 @@ Refactored from update.py for unified CLI hub import sys import time from pathlib import Path +from ...utils.paths import get_home_directory from typing import List, Optional, Dict, Any import argparse @@ -384,7 +385,7 @@ def run(args: argparse.Namespace) -> int: from setup.cli.base import __version__ # ✅ Inserted validation code - expected_home = Path.home().resolve() + expected_home = get_home_directory().resolve() actual_dir = args.install_dir.resolve() if not str(actual_dir).startswith(str(expected_home)): diff --git a/setup/components/mcp.py b/setup/components/mcp.py index f3d45b9..d7131ec 100644 --- a/setup/components/mcp.py +++ b/setup/components/mcp.py @@ -384,23 +384,147 @@ class MCPComponent(Component): """Check if MCP server is already installed""" try: result = self._run_command_cross_platform( - ["claude", "mcp", "list"], - capture_output=True, - text=True, + ["claude", "mcp", "list"], + capture_output=True, + text=True, timeout=60 ) - + if result.returncode != 0: self.logger.warning(f"Could not list MCP servers: {result.stderr}") return False - + # Parse output to check if server is installed output = result.stdout.lower() return server_name.lower() in output - + except (subprocess.TimeoutExpired, subprocess.SubprocessError) as e: self.logger.warning(f"Error checking MCP server status: {e}") return False + + def _detect_existing_mcp_servers_from_config(self) -> List[str]: + """Detect existing MCP servers from Claude Desktop config""" + detected_servers = [] + + try: + # Try to find Claude Desktop config file + config_paths = [ + self.install_dir / "claude_desktop_config.json", + Path.home() / ".claude" / "claude_desktop_config.json", + Path.home() / ".claude.json", # Claude CLI config + Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json", # Windows + Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json", # macOS + ] + + config_file = None + for path in config_paths: + if path.exists(): + config_file = path + break + + if not config_file: + self.logger.debug("No Claude Desktop config file found") + return detected_servers + + import json + with open(config_file, 'r') as f: + config = json.load(f) + + # Extract MCP server names from mcpServers section + mcp_servers = config.get("mcpServers", {}) + for server_name in mcp_servers.keys(): + # Map common name variations to our standard names + normalized_name = self._normalize_server_name(server_name) + if normalized_name and normalized_name in self.mcp_servers: + detected_servers.append(normalized_name) + + if detected_servers: + self.logger.info(f"Detected existing MCP servers from config: {detected_servers}") + + except Exception as e: + self.logger.warning(f"Could not read Claude Desktop config: {e}") + + return detected_servers + + def _detect_existing_mcp_servers_from_cli(self) -> List[str]: + """Detect existing MCP servers from Claude CLI""" + detected_servers = [] + + try: + result = self._run_command_cross_platform( + ["claude", "mcp", "list"], + capture_output=True, + text=True, + timeout=60 + ) + + if result.returncode != 0: + self.logger.debug(f"Could not list MCP servers: {result.stderr}") + return detected_servers + + # Parse the output to extract server names + output_lines = result.stdout.strip().split('\n') + for line in output_lines: + line = line.strip().lower() + if line and not line.startswith('#') and not line.startswith('no'): + # Extract server name (usually the first word or before first space/colon) + server_name = line.split()[0] if line.split() else "" + normalized_name = self._normalize_server_name(server_name) + if normalized_name and normalized_name in self.mcp_servers: + detected_servers.append(normalized_name) + + if detected_servers: + self.logger.info(f"Detected existing MCP servers from CLI: {detected_servers}") + + except Exception as e: + self.logger.warning(f"Could not detect existing MCP servers from CLI: {e}") + + return detected_servers + + def _normalize_server_name(self, server_name: str) -> Optional[str]: + """Normalize server name to match our internal naming""" + if not server_name: + return None + + server_name = server_name.lower().strip() + + # Map common variations to our standard names + name_mappings = { + "context7": "context7", + "sequential-thinking": "sequential-thinking", + "sequential": "sequential-thinking", + "magic": "magic", + "playwright": "playwright", + "serena": "serena", + "morphllm": "morphllm-fast-apply", + "morphllm-fast-apply": "morphllm-fast-apply", + "morph": "morphllm-fast-apply" + } + + return name_mappings.get(server_name) + + def _merge_server_lists(self, existing_servers: List[str], selected_servers: List[str], previous_servers: List[str]) -> List[str]: + """Merge existing, selected, and previously installed servers""" + all_servers = set() + + # Add all detected servers + all_servers.update(existing_servers) + all_servers.update(selected_servers) + all_servers.update(previous_servers) + + # Filter to only include servers we know how to install + valid_servers = [s for s in all_servers if s in self.mcp_servers] + + if valid_servers: + self.logger.info(f"Total servers to manage: {valid_servers}") + if existing_servers: + self.logger.info(f" - Existing: {existing_servers}") + if selected_servers: + self.logger.info(f" - Newly selected: {selected_servers}") + if previous_servers: + self.logger.info(f" - Previously installed: {previous_servers}") + + return valid_servers def _install_mcp_server(self, server_info: Dict[str, Any], config: Dict[str, Any]) -> bool: """Install a single MCP server""" @@ -506,7 +630,7 @@ class MCPComponent(Component): return False def _install(self, config: Dict[str, Any]) -> bool: - """Install MCP component""" + """Install MCP component with auto-detection of existing servers""" self.logger.info("Installing SuperClaude MCP servers...") # Validate prerequisites @@ -516,35 +640,59 @@ class MCPComponent(Component): self.logger.error(error) return False + # Auto-detect existing servers + self.logger.info("Auto-detecting existing MCP servers...") + existing_from_config = self._detect_existing_mcp_servers_from_config() + existing_from_cli = self._detect_existing_mcp_servers_from_cli() + existing_servers = list(set(existing_from_config + existing_from_cli)) + # Get selected servers from config selected_servers = config.get("selected_mcp_servers", []) - if not selected_servers: - self.logger.info("No MCP servers selected for installation.") + # Get previously installed servers from metadata + previous_servers = self.settings_manager.get_metadata_setting("mcp.servers", []) + + # Merge all server lists + all_servers = self._merge_server_lists(existing_servers, selected_servers, previous_servers) + + if not all_servers: + self.logger.info("No MCP servers detected or selected. Skipping MCP installation.") + # Still run post-install to update metadata return self._post_install() - self.logger.info(f"Installing selected MCP servers: {', '.join(selected_servers)}") + self.logger.info(f"Managing MCP servers: {', '.join(all_servers)}") - # Install each selected MCP server + # Install/verify each server installed_count = 0 failed_servers = [] - self.installed_servers_in_session = [] + verified_servers = [] - for server_name in selected_servers: + for server_name in all_servers: if server_name in self.mcp_servers: server_info = self.mcp_servers[server_name] - if self._install_mcp_server(server_info, config): - installed_count += 1 - self.installed_servers_in_session.append(server_name) - else: - failed_servers.append(server_name) - # Check if this is a required server - if server_info.get("required", False): - self.logger.error(f"Required MCP server {server_name} failed to install") - return False + # Check if already installed and working + if self._check_mcp_server_installed(server_name): + self.logger.info(f"MCP server {server_name} already installed and working") + installed_count += 1 + verified_servers.append(server_name) + else: + # Try to install + if self._install_mcp_server(server_info, config): + installed_count += 1 + verified_servers.append(server_name) + else: + failed_servers.append(server_name) + + # Check if this is a required server + if server_info.get("required", False): + self.logger.error(f"Required MCP server {server_name} failed to install") + return False else: - self.logger.warning(f"Unknown MCP server '{server_name}' selected for installation.") + self.logger.warning(f"Unknown MCP server '{server_name}' cannot be managed by SuperClaude") + + # Update the list of successfully managed servers + self.installed_servers_in_session = verified_servers # Verify installation if not config.get("dry_run", False): @@ -556,7 +704,7 @@ class MCPComponent(Component): text=True, timeout=60 ) - + if result.returncode == 0: self.logger.debug("MCP servers list:") for line in result.stdout.strip().split('\n'): @@ -564,15 +712,15 @@ class MCPComponent(Component): self.logger.debug(f" {line.strip()}") else: self.logger.warning("Could not verify MCP server installation") - + except Exception as e: self.logger.warning(f"Could not verify MCP installation: {e}") if failed_servers: self.logger.warning(f"Some MCP servers failed to install: {failed_servers}") - self.logger.success(f"MCP component partially installed ({installed_count} servers)") + self.logger.success(f"MCP component partially managed ({installed_count} servers)") else: - self.logger.success(f"MCP component installed successfully ({installed_count} servers)") + self.logger.success(f"MCP component successfully managing ({installed_count} servers)") return self._post_install() @@ -587,7 +735,8 @@ class MCPComponent(Component): self.settings_manager.add_component_registration("mcp", { "version": __version__, "category": "integration", - "servers_count": len(self.mcp_servers) + "servers_count": len(self.installed_servers_in_session), + "installed_servers": self.installed_servers_in_session }) self.logger.info("Updated metadata with MCP component registration") diff --git a/setup/components/mcp_docs.py b/setup/components/mcp_docs.py index 0e06c97..1625925 100644 --- a/setup/components/mcp_docs.py +++ b/setup/components/mcp_docs.py @@ -22,11 +22,13 @@ class MCPDocsComponent(Component): # Map server names to documentation files self.server_docs_map = { "context7": "MCP_Context7.md", - "sequential": "MCP_Sequential.md", + "sequential": "MCP_Sequential.md", + "sequential-thinking": "MCP_Sequential.md", # Handle both naming conventions "magic": "MCP_Magic.md", "playwright": "MCP_Playwright.md", "serena": "MCP_Serena.md", - "morphllm": "MCP_Morphllm.md" + "morphllm": "MCP_Morphllm.md", + "morphllm-fast-apply": "MCP_Morphllm.md" # Handle both naming conventions } super().__init__(install_dir, Path("")) @@ -39,7 +41,14 @@ class MCPDocsComponent(Component): "description": "MCP server documentation and usage guides", "category": "documentation" } - + + def is_reinstallable(self) -> bool: + """ + Allow mcp_docs to be reinstalled to handle different server selections. + This enables users to add or change MCP server documentation. + """ + return True + def set_selected_servers(self, selected_servers: List[str]) -> None: """Set which MCP servers were selected for documentation installation""" self.selected_servers = selected_servers @@ -81,19 +90,111 @@ class MCPDocsComponent(Component): files.append(self.server_docs_map[server_name]) return files + def _detect_existing_mcp_servers_from_config(self) -> List[str]: + """Detect existing MCP servers from Claude Desktop config""" + detected_servers = [] + + try: + # Try to find Claude Desktop config file + config_paths = [ + self.install_dir / "claude_desktop_config.json", + Path.home() / ".claude" / "claude_desktop_config.json", + Path.home() / ".claude.json", # Claude CLI config + Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json", # Windows + Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json", # macOS + ] + + config_file = None + for path in config_paths: + if path.exists(): + config_file = path + break + + if not config_file: + self.logger.debug("No Claude Desktop config file found") + return detected_servers + + import json + with open(config_file, 'r') as f: + config = json.load(f) + + # Extract MCP server names from mcpServers section + mcp_servers = config.get("mcpServers", {}) + for server_name in mcp_servers.keys(): + # Map common name variations to our doc file names + normalized_name = self._normalize_server_name(server_name) + if normalized_name and normalized_name in self.server_docs_map: + detected_servers.append(normalized_name) + + if detected_servers: + self.logger.info(f"Detected existing MCP servers from config: {detected_servers}") + + except Exception as e: + self.logger.warning(f"Could not read Claude Desktop config: {e}") + + return detected_servers + + def _normalize_server_name(self, server_name: str) -> Optional[str]: + """Normalize server name to match our documentation mapping""" + if not server_name: + return None + + server_name = server_name.lower().strip() + + # Map common variations to our server_docs_map keys + name_mappings = { + "context7": "context7", + "sequential-thinking": "sequential-thinking", + "sequential": "sequential-thinking", + "magic": "magic", + "playwright": "playwright", + "serena": "serena", + "morphllm": "morphllm", + "morphllm-fast-apply": "morphllm", + "morph": "morphllm" + } + + return name_mappings.get(server_name) + def _install(self, config: Dict[str, Any]) -> bool: - """Install MCP documentation component""" + """Install MCP documentation component with auto-detection""" self.logger.info("Installing MCP server documentation...") - + + # Auto-detect existing servers + self.logger.info("Auto-detecting existing MCP servers for documentation...") + detected_servers = self._detect_existing_mcp_servers_from_config() + # Get selected servers from config selected_servers = config.get("selected_mcp_servers", []) - self.set_selected_servers(selected_servers) - self.component_files = self._discover_component_files() - if not selected_servers: - self.logger.info("No MCP servers selected - skipping documentation installation") + # Get previously documented servers from metadata + previous_servers = self.settings_manager.get_metadata_setting("components.mcp_docs.servers_documented", []) + + # Merge all server lists + all_servers = list(set(detected_servers + selected_servers + previous_servers)) + + # Filter to only servers we have documentation for + valid_servers = [s for s in all_servers if s in self.server_docs_map] + + if not valid_servers: + self.logger.info("No MCP servers detected or selected for documentation installation") + # Still proceed to update metadata + self.set_selected_servers([]) + self.component_files = [] return self._post_install() + self.logger.info(f"Installing documentation for MCP servers: {', '.join(valid_servers)}") + if detected_servers: + self.logger.info(f" - Detected from config: {detected_servers}") + if selected_servers: + self.logger.info(f" - Newly selected: {selected_servers}") + if previous_servers: + self.logger.info(f" - Previously documented: {previous_servers}") + + # Set the servers for which we'll install documentation + self.set_selected_servers(valid_servers) + self.component_files = self._discover_component_files() + # Validate installation success, errors = self.validate_prerequisites() if not success: @@ -106,15 +207,18 @@ class MCPDocsComponent(Component): if not files_to_install: self.logger.warning("No MCP documentation files found to install") - return self._post_install() + return False # Copy documentation files success_count = 0 + successfully_copied_files = [] + for source, target in files_to_install: self.logger.debug(f"Copying {source.name} to {target}") - + if self.file_manager.copy_file(source, target): success_count += 1 + successfully_copied_files.append(source.name) self.logger.debug(f"Successfully copied {source.name}") else: self.logger.error(f"Failed to copy {source.name}") @@ -123,7 +227,9 @@ class MCPDocsComponent(Component): self.logger.error(f"Only {success_count}/{len(files_to_install)} documentation files copied successfully") return False - self.logger.success(f"MCP documentation installed successfully ({success_count} files for {len(selected_servers)} servers)") + # Update component_files to only include successfully copied files + self.component_files = successfully_copied_files + self.logger.success(f"MCP documentation installed successfully ({success_count} files for {len(valid_servers)} servers)") return self._post_install() diff --git a/setup/core/validator.py b/setup/core/validator.py index 8d36ec7..9ff130a 100644 --- a/setup/core/validator.py +++ b/setup/core/validator.py @@ -8,6 +8,7 @@ import shutil from typing import Tuple, List, Dict, Any, Optional from pathlib import Path import re +from ..utils.paths import get_home_directory # Handle packaging import - if not available, use a simple version comparison try: @@ -407,7 +408,7 @@ class Validator: # Check disk space if "disk_space_mb" in requirements: success, message = self.check_disk_space( - Path.home(), + get_home_directory(), requirements["disk_space_mb"] ) if not success: @@ -504,7 +505,7 @@ class Validator: # Add disk space info try: - home_path = Path.home() + home_path = get_home_directory() stat_result = shutil.disk_usage(home_path) info["disk_space"] = { "total_gb": stat_result.total / (1024**3), @@ -620,7 +621,7 @@ class Validator: diagnostics["recommendations"].append(self.get_installation_help("claude_cli")) # Check disk space - disk_success, disk_msg = self.check_disk_space(Path.home()) + disk_success, disk_msg = self.check_disk_space(get_home_directory()) diagnostics["checks"]["disk_space"] = { "status": "pass" if disk_success else "fail", "message": disk_msg diff --git a/setup/data/features.json b/setup/data/features.json index d3c6268..02f00d3 100644 --- a/setup/data/features.json +++ b/setup/data/features.json @@ -2,7 +2,7 @@ "components": { "core": { "name": "core", - "version": "4.1.3", + "version": "4.1.4", "description": "SuperClaude framework documentation and core files", "category": "core", "dependencies": [], @@ -11,7 +11,7 @@ }, "commands": { "name": "commands", - "version": "4.1.3", + "version": "4.1.4", "description": "SuperClaude slash command definitions", "category": "commands", "dependencies": ["core"], @@ -20,7 +20,7 @@ }, "mcp": { "name": "mcp", - "version": "4.1.3", + "version": "4.1.4", "description": "MCP server configuration management via .claude.json", "category": "integration", "dependencies": ["core"], @@ -29,7 +29,7 @@ }, "modes": { "name": "modes", - "version": "4.1.3", + "version": "4.1.4", "description": "SuperClaude behavioral modes (Brainstorming, Introspection, Task Management, Token Efficiency)", "category": "modes", "dependencies": ["core"], @@ -38,7 +38,7 @@ }, "mcp_docs": { "name": "mcp_docs", - "version": "4.1.3", + "version": "4.1.4", "description": "MCP server documentation and usage guides", "category": "documentation", "dependencies": ["core"], @@ -47,7 +47,7 @@ }, "agents": { "name": "agents", - "version": "4.1.3", + "version": "4.1.4", "description": "14 specialized AI agents with domain expertise and intelligent routing", "category": "agents", "dependencies": ["core"], diff --git a/setup/utils/environment.py b/setup/utils/environment.py index fa0dd99..f038f72 100644 --- a/setup/utils/environment.py +++ b/setup/utils/environment.py @@ -12,12 +12,13 @@ from typing import Dict, Optional from datetime import datetime from .ui import display_info, display_success, display_warning, Colors from .logger import get_logger +from .paths import get_home_directory def _get_env_tracking_file() -> Path: """Get path to environment variable tracking file""" from .. import DEFAULT_INSTALL_DIR - install_dir = Path.home() / ".claude" + install_dir = get_home_directory() / ".claude" install_dir.mkdir(exist_ok=True) return install_dir / "superclaude_env_vars.json" @@ -90,7 +91,7 @@ def detect_shell_config() -> Optional[Path]: Returns: Path to the shell configuration file, or None if not found """ - home = Path.home() + home = get_home_directory() # Check in order of preference configs = [ @@ -340,7 +341,7 @@ def cleanup_environment_variables(env_vars_to_remove: Dict[str, str], create_res def _create_restore_script(env_vars: Dict[str, str]) -> Optional[Path]: """Create a script to restore environment variables""" try: - home = Path.home() + home = get_home_directory() if os.name == 'nt': # Windows script_path = home / "restore_superclaude_env.bat" with open(script_path, 'w') as f: @@ -423,7 +424,7 @@ def create_env_file(api_keys: Dict[str, str], env_file_path: Optional[Path] = No True if .env file was created successfully, False otherwise """ if env_file_path is None: - env_file_path = Path.home() / ".env" + env_file_path = get_home_directory() / ".env" logger = get_logger() diff --git a/setup/utils/logger.py b/setup/utils/logger.py index 887168d..55901e2 100644 --- a/setup/utils/logger.py +++ b/setup/utils/logger.py @@ -11,6 +11,7 @@ from enum import Enum from .ui import Colors from .symbols import symbols +from .paths import get_home_directory class LogLevel(Enum): @@ -36,7 +37,7 @@ class Logger: file_level: Minimum level for file output """ self.name = name - self.log_dir = log_dir or (Path.home() / ".claude" / "logs") + self.log_dir = log_dir or (get_home_directory() / ".claude" / "logs") self.console_level = console_level self.file_level = file_level self.session_start = datetime.now() diff --git a/setup/utils/paths.py b/setup/utils/paths.py new file mode 100644 index 0000000..73a8ec2 --- /dev/null +++ b/setup/utils/paths.py @@ -0,0 +1,54 @@ +""" +Path utilities for SuperClaude installation system +Handles cross-platform path operations and immutable distro support +""" + +import os +from pathlib import Path + + +def get_home_directory() -> Path: + """ + Get the correct home directory path, handling immutable distros. + + On immutable distros like Fedora Silverblue/Universal Blue, + the home directory is at /var/home/$USER instead of /home/$USER. + This function properly detects the actual home directory. + + Returns: + Path: The actual home directory path + """ + # First try the standard method + try: + home = Path.home() + # Verify the path actually exists and is accessible + if home.exists() and home.is_dir(): + return home + except Exception: + pass + + # Fallback methods for edge cases and immutable distros + + # Method 1: Use $HOME environment variable + home_env = os.environ.get('HOME') + if home_env: + home_path = Path(home_env) + if home_path.exists() and home_path.is_dir(): + return home_path + + # Method 2: Check for immutable distro patterns + username = os.environ.get('USER') or os.environ.get('USERNAME') + if username: + # Check common immutable distro paths + immutable_paths = [ + Path(f'/var/home/{username}'), # Fedora Silverblue/Universal Blue + Path(f'/home/{username}'), # Standard Linux + ] + + for path in immutable_paths: + if path.exists() and path.is_dir(): + return path + + # Method 3: Last resort - use the original Path.home() even if it seems wrong + # This ensures we don't crash the installation + return Path.home() \ No newline at end of file diff --git a/setup/utils/security.py b/setup/utils/security.py index 1a06d42..acf716a 100644 --- a/setup/utils/security.py +++ b/setup/utils/security.py @@ -32,6 +32,7 @@ import os from pathlib import Path from typing import List, Optional, Tuple, Set import urllib.parse +from .paths import get_home_directory class SecurityValidator: @@ -410,7 +411,7 @@ class SecurityValidator: if is_claude_dir: try: - home_path = Path.home() + home_path = get_home_directory() except (RuntimeError, OSError): # If we can't determine home directory, skip .claude special handling cls._log_security_decision("WARN", f"Cannot determine home directory for .claude validation: {abs_target}") @@ -432,7 +433,7 @@ class SecurityValidator: if ':' in abs_target_str and '\\users\\' in abs_target_str: try: # Check if target is within the user's actual home directory - home_path = Path.home() + home_path = get_home_directory() abs_target.relative_to(home_path) # Path is valid - within user's home directory except ValueError: diff --git a/setup/utils/updater.py b/setup/utils/updater.py index e7aff1c..896935b 100644 --- a/setup/utils/updater.py +++ b/setup/utils/updater.py @@ -17,13 +17,14 @@ from datetime import datetime, timedelta from .ui import display_info, display_warning, display_success, Colors from .logger import get_logger +from .paths import get_home_directory class UpdateChecker: """Handles automatic update checking for SuperClaude""" PYPI_URL = "https://pypi.org/pypi/SuperClaude/json" - CACHE_FILE = Path.home() / ".claude" / ".update_check" + CACHE_FILE = get_home_directory() / ".claude" / ".update_check" CHECK_INTERVAL = 86400 # 24 hours in seconds TIMEOUT = 2 # seconds @@ -162,7 +163,7 @@ class UpdateChecker: ) if result.returncode == 0: # Check if it's a user installation - if '--user' in result.stdout or Path.home() in Path(result.stdout): + if '--user' in result.stdout or get_home_directory() in Path(result.stdout): return 'pip-user' return 'pip' except: