External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-29 16:16:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial commit: SuperClaude v3 Beta clean architecture

Browse Source 
Complete foundational restructure with:
- Simplified project architecture
- Comprehensive documentation system
- Modern installation framework
- Clean configuration management
- Updated profiles and settings

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
2025-07-14 14:28:11 +02:00
commit 59d74b8af2
69 changed files with 17543 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
setup/components/__init__.py Normal file
View File

@@ -0,0 +1,13 @@
"""Component implementations for SuperClaude installation system"""
from .core import CoreComponent
from .commands import CommandsComponent
from .mcp import MCPComponent
from .hooks import HooksComponent
__all__ = [
'CoreComponent',
'CommandsComponent',
'MCPComponent',
'HooksComponent'
]

339
setup/components/commands.py Normal file
View File

@@ -0,0 +1,339 @@
"""
Commands component for SuperClaude slash command definitions
"""
from typing import Dict, List, Tuple, Any
from pathlib import Path
from ..base.component import Component
from ..core.file_manager import FileManager
from ..core.settings_manager import SettingsManager
from ..utils.security import SecurityValidator
from ..utils.logger import get_logger
class CommandsComponent(Component):
"""SuperClaude slash commands component"""
def __init__(self, install_dir: Path = None):
"""Initialize commands component"""
super().__init__(install_dir)
self.logger = get_logger()
self.file_manager = FileManager()
self.settings_manager = SettingsManager(self.install_dir)
# Define command files to install
self.command_files = [
"analyze.md",
"build.md",
"cleanup.md",
"design.md",
"document.md",
"estimate.md",
"explain.md",
"git.md",
"improve.md",
"index.md",
"load.md",
"spawn.md",
"task.md",
"test.md",
"troubleshoot.md"
]
def get_metadata(self) -> Dict[str, str]:
"""Get component metadata"""
return {
"name": "commands",
"version": "3.0.0",
"description": "SuperClaude slash command definitions",
"category": "commands"
}
def validate_prerequisites(self) -> Tuple[bool, List[str]]:
"""Check prerequisites"""
errors = []
# Check if we have read access to source files
source_dir = self._get_source_dir()
if not source_dir.exists():
errors.append(f"Source directory not found: {source_dir}")
return False, errors
# Check if all required command files exist
missing_files = []
for filename in self.command_files:
source_file = source_dir / filename
if not source_file.exists():
missing_files.append(filename)
if missing_files:
errors.append(f"Missing command files: {missing_files}")
# Check write permissions to install directory
commands_dir = self.install_dir / "commands"
has_perms, missing = SecurityValidator.check_permissions(
self.install_dir, {'write'}
)
if not has_perms:
errors.append(f"No write permissions to {self.install_dir}: {missing}")
# Validate installation target
is_safe, validation_errors = SecurityValidator.validate_installation_target(commands_dir)
if not is_safe:
errors.extend(validation_errors)
return len(errors) == 0, errors
def get_files_to_install(self) -> List[Tuple[Path, Path]]:
"""Get files to install"""
source_dir = self._get_source_dir()
files = []
for filename in self.command_files:
source = source_dir / filename
target = self.install_dir / "commands" / filename
files.append((source, target))
return files
def get_settings_modifications(self) -> Dict[str, Any]:
"""Get settings modifications"""
return {
"components": {
"commands": {
"version": "3.0.0",
"installed": True,
"files_count": len(self.command_files)
}
}
}
def install(self, config: Dict[str, Any]) -> bool:
"""Install commands component"""
try:
self.logger.info("Installing SuperClaude command definitions...")
# Validate installation
success, errors = self.validate_prerequisites()
if not success:
for error in errors:
self.logger.error(error)
return False
# Get files to install
files_to_install = self.get_files_to_install()
# Validate all files for security
source_dir = self._get_source_dir()
commands_dir = self.install_dir / "commands"
is_safe, security_errors = SecurityValidator.validate_component_files(
files_to_install, source_dir, commands_dir
)
if not is_safe:
for error in security_errors:
self.logger.error(f"Security validation failed: {error}")
return False
# Ensure commands directory exists
if not self.file_manager.ensure_directory(commands_dir):
self.logger.error(f"Could not create commands directory: {commands_dir}")
return False
# Copy command files
success_count = 0
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
self.logger.debug(f"Successfully copied {source.name}")
else:
self.logger.error(f"Failed to copy {source.name}")
if success_count != len(files_to_install):
self.logger.error(f"Only {success_count}/{len(files_to_install)} command files copied successfully")
return False
# Update settings.json
try:
settings_mods = self.get_settings_modifications()
self.settings_manager.update_settings(settings_mods)
self.logger.info("Updated settings.json with commands component registration")
except Exception as e:
self.logger.error(f"Failed to update settings.json: {e}")
return False
self.logger.success(f"Commands component installed successfully ({success_count} command files)")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during commands installation: {e}")
return False
def uninstall(self) -> bool:
"""Uninstall commands component"""
try:
self.logger.info("Uninstalling SuperClaude commands component...")
# Remove command files
commands_dir = self.install_dir / "commands"
removed_count = 0
for filename in self.command_files:
file_path = commands_dir / filename
if self.file_manager.remove_file(file_path):
removed_count += 1
self.logger.debug(f"Removed {filename}")
else:
self.logger.warning(f"Could not remove {filename}")
# Remove commands directory if empty
try:
if commands_dir.exists():
remaining_files = list(commands_dir.iterdir())
if not remaining_files:
commands_dir.rmdir()
self.logger.debug("Removed empty commands directory")
except Exception as e:
self.logger.warning(f"Could not remove commands directory: {e}")
# Update settings.json to remove commands component
try:
if self.settings_manager.is_component_installed("commands"):
self.settings_manager.remove_component_registration("commands")
self.logger.info("Removed commands component from settings.json")
except Exception as e:
self.logger.warning(f"Could not update settings.json: {e}")
self.logger.success(f"Commands component uninstalled ({removed_count} files removed)")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during commands uninstallation: {e}")
return False
def get_dependencies(self) -> List[str]:
"""Get dependencies"""
return ["core"]
def update(self, config: Dict[str, Any]) -> bool:
"""Update commands component"""
try:
self.logger.info("Updating SuperClaude commands component...")
# Check current version
current_version = self.settings_manager.get_component_version("commands")
target_version = self.get_metadata()["version"]
if current_version == target_version:
self.logger.info(f"Commands component already at version {target_version}")
return True
self.logger.info(f"Updating commands component from {current_version} to {target_version}")
# Create backup of existing command files
commands_dir = self.install_dir / "commands"
backup_files = []
if commands_dir.exists():
for filename in self.command_files:
file_path = commands_dir / filename
if file_path.exists():
backup_path = self.file_manager.backup_file(file_path)
if backup_path:
backup_files.append(backup_path)
self.logger.debug(f"Backed up {filename}")
# Perform installation (overwrites existing files)
success = self.install(config)
if success:
# Remove backup files on successful update
for backup_path in backup_files:
try:
backup_path.unlink()
except Exception:
pass # Ignore cleanup errors
self.logger.success(f"Commands component updated to version {target_version}")
else:
# Restore from backup on failure
self.logger.warning("Update failed, restoring from backup...")
for backup_path in backup_files:
try:
original_path = backup_path.with_suffix('')
backup_path.rename(original_path)
self.logger.debug(f"Restored {original_path.name}")
except Exception as e:
self.logger.error(f"Could not restore {backup_path}: {e}")
return success
except Exception as e:
self.logger.exception(f"Unexpected error during commands update: {e}")
return False
def validate_installation(self) -> Tuple[bool, List[str]]:
"""Validate commands component installation"""
errors = []
# Check if commands directory exists
commands_dir = self.install_dir / "commands"
if not commands_dir.exists():
errors.append("Commands directory not found")
return False, errors
# Check if all command files exist
for filename in self.command_files:
file_path = commands_dir / filename
if not file_path.exists():
errors.append(f"Missing command file: {filename}")
elif not file_path.is_file():
errors.append(f"Command file is not a regular file: {filename}")
# Check settings.json registration
if not self.settings_manager.is_component_installed("commands"):
errors.append("Commands component not registered in settings.json")
else:
# Check version matches
installed_version = self.settings_manager.get_component_version("commands")
expected_version = self.get_metadata()["version"]
if installed_version != expected_version:
errors.append(f"Version mismatch: installed {installed_version}, expected {expected_version}")
return len(errors) == 0, errors
def _get_source_dir(self) -> Path:
"""Get source directory for command files"""
# Assume we're in SuperClaude/setup/components/commands.py
# and command files are in SuperClaude/SuperClaude/Commands/
project_root = Path(__file__).parent.parent.parent
return project_root / "SuperClaude" / "Commands"
def get_size_estimate(self) -> int:
"""Get estimated installation size"""
total_size = 0
source_dir = self._get_source_dir()
for filename in self.command_files:
file_path = source_dir / filename
if file_path.exists():
total_size += file_path.stat().st_size
# Add overhead for directory and settings
total_size += 5120 # ~5KB overhead
return total_size
def get_installation_summary(self) -> Dict[str, Any]:
"""Get installation summary"""
return {
"component": self.get_metadata()["name"],
"version": self.get_metadata()["version"],
"files_installed": len(self.command_files),
"command_files": self.command_files,
"estimated_size": self.get_size_estimate(),
"install_directory": str(self.install_dir / "commands"),
"dependencies": self.get_dependencies()
}

338
setup/components/core.py Normal file
View File

@@ -0,0 +1,338 @@
"""
Core component for SuperClaude framework files installation
"""
from typing import Dict, List, Tuple, Any
from pathlib import Path
import json
import shutil
from ..base.component import Component
from ..core.file_manager import FileManager
from ..core.settings_manager import SettingsManager
from ..utils.security import SecurityValidator
from ..utils.logger import get_logger
class CoreComponent(Component):
"""Core SuperClaude framework files component"""
def __init__(self, install_dir: Path = None):
"""Initialize core component"""
super().__init__(install_dir)
self.logger = get_logger()
self.file_manager = FileManager()
self.settings_manager = SettingsManager(self.install_dir)
# Define framework files to install
self.framework_files = [
"CLAUDE.md",
"COMMANDS.md",
"FLAGS.md",
"PRINCIPLES.md",
"RULES.md",
"MCP.md",
"PERSONAS.md",
"ORCHESTRATOR.md",
"MODES.md"
]
def get_metadata(self) -> Dict[str, str]:
"""Get component metadata"""
return {
"name": "core",
"version": "3.0.0",
"description": "SuperClaude framework documentation and core files",
"category": "core"
}
def validate_prerequisites(self) -> Tuple[bool, List[str]]:
"""Check prerequisites for core component"""
errors = []
# Check if we have read access to source files
source_dir = self._get_source_dir()
if not source_dir.exists():
errors.append(f"Source directory not found: {source_dir}")
return False, errors
# Check if all required framework files exist
missing_files = []
for filename in self.framework_files:
source_file = source_dir / filename
if not source_file.exists():
missing_files.append(filename)
if missing_files:
errors.append(f"Missing framework files: {missing_files}")
# Check write permissions to install directory
has_perms, missing = SecurityValidator.check_permissions(
self.install_dir, {'write'}
)
if not has_perms:
errors.append(f"No write permissions to {self.install_dir}: {missing}")
# Validate installation target
is_safe, validation_errors = SecurityValidator.validate_installation_target(self.install_dir)
if not is_safe:
errors.extend(validation_errors)
return len(errors) == 0, errors
def get_files_to_install(self) -> List[Tuple[Path, Path]]:
"""Get list of files to install"""
source_dir = self._get_source_dir()
files = []
for filename in self.framework_files:
source = source_dir / filename
target = self.install_dir / filename
files.append((source, target))
return files
def get_settings_modifications(self) -> Dict[str, Any]:
"""Get settings.json modifications"""
return {
"framework": {
"version": "3.0.0",
"name": "SuperClaude",
"description": "AI-enhanced development framework for Claude Code",
"installation_type": "global",
"components": ["core"]
},
"superclaude": {
"enabled": True,
"version": "3.0.0",
"profile": "default",
"auto_update": False
}
}
def install(self, config: Dict[str, Any]) -> bool:
"""Install core component"""
try:
self.logger.info("Installing SuperClaude core framework files...")
# Validate installation
success, errors = self.validate_prerequisites()
if not success:
for error in errors:
self.logger.error(error)
return False
# Get files to install
files_to_install = self.get_files_to_install()
# Validate all files for security
source_dir = self._get_source_dir()
is_safe, security_errors = SecurityValidator.validate_component_files(
files_to_install, source_dir, self.install_dir
)
if not is_safe:
for error in security_errors:
self.logger.error(f"Security validation failed: {error}")
return False
# Ensure install directory exists
if not self.file_manager.ensure_directory(self.install_dir):
self.logger.error(f"Could not create install directory: {self.install_dir}")
return False
# Copy framework files
success_count = 0
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
self.logger.debug(f"Successfully copied {source.name}")
else:
self.logger.error(f"Failed to copy {source.name}")
if success_count != len(files_to_install):
self.logger.error(f"Only {success_count}/{len(files_to_install)} files copied successfully")
return False
# Create or update settings.json
try:
settings_mods = self.get_settings_modifications()
self.settings_manager.update_settings(settings_mods)
self.logger.info("Updated settings.json with framework configuration")
except Exception as e:
self.logger.error(f"Failed to update settings.json: {e}")
return False
# Create additional directories for other components
additional_dirs = ["commands", "hooks", "backups", "logs"]
for dirname in additional_dirs:
dir_path = self.install_dir / dirname
if not self.file_manager.ensure_directory(dir_path):
self.logger.warning(f"Could not create directory: {dir_path}")
self.logger.success(f"Core component installed successfully ({success_count} files)")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during core installation: {e}")
return False
def uninstall(self) -> bool:
"""Uninstall core component"""
try:
self.logger.info("Uninstalling SuperClaude core component...")
# Remove framework files
removed_count = 0
for filename in self.framework_files:
file_path = self.install_dir / filename
if self.file_manager.remove_file(file_path):
removed_count += 1
self.logger.debug(f"Removed {filename}")
else:
self.logger.warning(f"Could not remove {filename}")
# Update settings.json to remove core component
try:
if self.settings_manager.is_component_installed("core"):
self.settings_manager.remove_component_registration("core")
self.logger.info("Removed core component from settings.json")
except Exception as e:
self.logger.warning(f"Could not update settings.json: {e}")
self.logger.success(f"Core component uninstalled ({removed_count} files removed)")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during core uninstallation: {e}")
return False
def get_dependencies(self) -> List[str]:
"""Get component dependencies (core has none)"""
return []
def update(self, config: Dict[str, Any]) -> bool:
"""Update core component"""
try:
self.logger.info("Updating SuperClaude core component...")
# Check current version
current_version = self.settings_manager.get_component_version("core")
target_version = self.get_metadata()["version"]
if current_version == target_version:
self.logger.info(f"Core component already at version {target_version}")
return True
self.logger.info(f"Updating core component from {current_version} to {target_version}")
# Create backup of existing files
backup_files = []
for filename in self.framework_files:
file_path = self.install_dir / filename
if file_path.exists():
backup_path = self.file_manager.backup_file(file_path)
if backup_path:
backup_files.append(backup_path)
self.logger.debug(f"Backed up {filename}")
# Perform installation (overwrites existing files)
success = self.install(config)
if success:
# Remove backup files on successful update
for backup_path in backup_files:
try:
backup_path.unlink()
except Exception:
pass # Ignore cleanup errors
self.logger.success(f"Core component updated to version {target_version}")
else:
# Restore from backup on failure
self.logger.warning("Update failed, restoring from backup...")
for backup_path in backup_files:
try:
original_path = backup_path.with_suffix('')
shutil.move(str(backup_path), str(original_path))
self.logger.debug(f"Restored {original_path.name}")
except Exception as e:
self.logger.error(f"Could not restore {backup_path}: {e}")
return success
except Exception as e:
self.logger.exception(f"Unexpected error during core update: {e}")
return False
def validate_installation(self) -> Tuple[bool, List[str]]:
"""Validate core component installation"""
errors = []
# Check if all framework files exist
for filename in self.framework_files:
file_path = self.install_dir / filename
if not file_path.exists():
errors.append(f"Missing framework file: {filename}")
elif not file_path.is_file():
errors.append(f"Framework file is not a regular file: {filename}")
# Check settings.json registration
if not self.settings_manager.is_component_installed("core"):
errors.append("Core component not registered in settings.json")
else:
# Check version matches
installed_version = self.settings_manager.get_component_version("core")
expected_version = self.get_metadata()["version"]
if installed_version != expected_version:
errors.append(f"Version mismatch: installed {installed_version}, expected {expected_version}")
# Check settings.json structure
try:
framework_config = self.settings_manager.get_setting("framework")
if not framework_config:
errors.append("Missing framework configuration in settings.json")
else:
required_keys = ["version", "name", "description"]
for key in required_keys:
if key not in framework_config:
errors.append(f"Missing framework.{key} in settings.json")
except Exception as e:
errors.append(f"Could not validate settings.json: {e}")
return len(errors) == 0, errors
def _get_source_dir(self) -> Path:
"""Get source directory for framework files"""
# Assume we're in SuperClaude/setup/components/core.py
# and framework files are in SuperClaude/SuperClaude/Core/
project_root = Path(__file__).parent.parent.parent
return project_root / "SuperClaude" / "Core"
def get_size_estimate(self) -> int:
"""Get estimated installation size"""
total_size = 0
source_dir = self._get_source_dir()
for filename in self.framework_files:
file_path = source_dir / filename
if file_path.exists():
total_size += file_path.stat().st_size
# Add overhead for settings.json and directories
total_size += 10240 # ~10KB overhead
return total_size
def get_installation_summary(self) -> Dict[str, Any]:
"""Get installation summary"""
return {
"component": self.get_metadata()["name"],
"version": self.get_metadata()["version"],
"files_installed": len(self.framework_files),
"framework_files": self.framework_files,
"estimated_size": self.get_size_estimate(),
"install_directory": str(self.install_dir),
"dependencies": self.get_dependencies()
}

425
setup/components/hooks.py Normal file
View File

@@ -0,0 +1,425 @@
"""
Hooks component for Claude Code hooks integration (future-ready)
"""
from typing import Dict, List, Tuple, Any
from pathlib import Path
from ..base.component import Component
from ..core.file_manager import FileManager
from ..core.settings_manager import SettingsManager
from ..utils.security import SecurityValidator
from ..utils.logger import get_logger
class HooksComponent(Component):
"""Claude Code hooks integration component"""
def __init__(self, install_dir: Path = None):
"""Initialize hooks component"""
super().__init__(install_dir)
self.logger = get_logger()
self.file_manager = FileManager()
self.settings_manager = SettingsManager(self.install_dir)
# Define hook files to install (when hooks are ready)
self.hook_files = [
"pre_tool_use.py",
"post_tool_use.py",
"error_handler.py",
"context_accumulator.py",
"performance_monitor.py"
]
def get_metadata(self) -> Dict[str, str]:
"""Get component metadata"""
return {
"name": "hooks",
"version": "3.0.0",
"description": "Claude Code hooks integration (future-ready)",
"category": "integration"
}
def validate_prerequisites(self) -> Tuple[bool, List[str]]:
"""Check prerequisites"""
errors = []
# Check if source directory exists (when hooks are implemented)
source_dir = self._get_source_dir()
if not source_dir.exists():
# This is expected for now - hooks are future-ready
self.logger.debug(f"Hooks source directory not found: {source_dir} (expected for future implementation)")
# Check write permissions to install directory
hooks_dir = self.install_dir / "hooks"
has_perms, missing = SecurityValidator.check_permissions(
self.install_dir, {'write'}
)
if not has_perms:
errors.append(f"No write permissions to {self.install_dir}: {missing}")
# Validate installation target
is_safe, validation_errors = SecurityValidator.validate_installation_target(hooks_dir)
if not is_safe:
errors.extend(validation_errors)
return len(errors) == 0, errors
def get_files_to_install(self) -> List[Tuple[Path, Path]]:
"""Get files to install"""
source_dir = self._get_source_dir()
files = []
# Only include files that actually exist
for filename in self.hook_files:
source = source_dir / filename
if source.exists():
target = self.install_dir / "hooks" / filename
files.append((source, target))
return files
def get_settings_modifications(self) -> Dict[str, Any]:
"""Get settings modifications"""
hooks_dir = self.install_dir / "hooks"
# Build hooks configuration based on available files
hook_config = {}
for filename in self.hook_files:
hook_path = hooks_dir / filename
if hook_path.exists():
hook_name = filename.replace('.py', '')
hook_config[hook_name] = [str(hook_path)]
settings_mods = {
"components": {
"hooks": {
"version": "3.0.0",
"installed": True,
"files_count": len(hook_config)
}
}
}
# Only add hooks configuration if we have actual hook files
if hook_config:
settings_mods["hooks"] = {
"enabled": True,
**hook_config
}
return settings_mods
def install(self, config: Dict[str, Any]) -> bool:
"""Install hooks component"""
try:
self.logger.info("Installing SuperClaude hooks component...")
# This component is future-ready - hooks aren't implemented yet
source_dir = self._get_source_dir()
if not source_dir.exists():
self.logger.info("Hooks are not yet implemented - installing placeholder component")
# Create placeholder hooks directory
hooks_dir = self.install_dir / "hooks"
if not self.file_manager.ensure_directory(hooks_dir):
self.logger.error(f"Could not create hooks directory: {hooks_dir}")
return False
# Create placeholder file
placeholder_content = '''"""
SuperClaude Hooks - Future Implementation
This directory is reserved for Claude Code hooks integration.
Hooks will provide lifecycle management and automation capabilities.
Planned hooks:
- pre_tool_use: Execute before tool usage
- post_tool_use: Execute after tool completion
- error_handler: Handle tool errors and recovery
- context_accumulator: Manage context across operations
- performance_monitor: Track and optimize performance
For more information, see SuperClaude documentation.
"""
# Placeholder for future hooks implementation
def placeholder_hook():
"""Placeholder hook function"""
pass
'''
placeholder_path = hooks_dir / "PLACEHOLDER.py"
try:
with open(placeholder_path, 'w') as f:
f.write(placeholder_content)
self.logger.debug("Created hooks placeholder file")
except Exception as e:
self.logger.warning(f"Could not create placeholder file: {e}")
# Update settings with placeholder registration
try:
settings_mods = {
"components": {
"hooks": {
"version": "3.0.0",
"installed": True,
"status": "placeholder",
"files_count": 0
}
}
}
self.settings_manager.update_settings(settings_mods)
self.logger.info("Updated settings.json with hooks component registration")
except Exception as e:
self.logger.error(f"Failed to update settings.json: {e}")
return False
self.logger.success("Hooks component installed successfully (placeholder)")
return True
# If hooks source directory exists, install actual hooks
self.logger.info("Installing actual hook files...")
# Validate installation
success, errors = self.validate_prerequisites()
if not success:
for error in errors:
self.logger.error(error)
return False
# Get files to install
files_to_install = self.get_files_to_install()
if not files_to_install:
self.logger.warning("No hook files found to install")
return False
# Validate all files for security
hooks_dir = self.install_dir / "hooks"
is_safe, security_errors = SecurityValidator.validate_component_files(
files_to_install, source_dir, hooks_dir
)
if not is_safe:
for error in security_errors:
self.logger.error(f"Security validation failed: {error}")
return False
# Ensure hooks directory exists
if not self.file_manager.ensure_directory(hooks_dir):
self.logger.error(f"Could not create hooks directory: {hooks_dir}")
return False
# Copy hook files
success_count = 0
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
self.logger.debug(f"Successfully copied {source.name}")
else:
self.logger.error(f"Failed to copy {source.name}")
if success_count != len(files_to_install):
self.logger.error(f"Only {success_count}/{len(files_to_install)} hook files copied successfully")
return False
# Update settings.json
try:
settings_mods = self.get_settings_modifications()
self.settings_manager.update_settings(settings_mods)
self.logger.info("Updated settings.json with hooks configuration")
except Exception as e:
self.logger.error(f"Failed to update settings.json: {e}")
return False
self.logger.success(f"Hooks component installed successfully ({success_count} hook files)")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during hooks installation: {e}")
return False
def uninstall(self) -> bool:
"""Uninstall hooks component"""
try:
self.logger.info("Uninstalling SuperClaude hooks component...")
# Remove hook files and placeholder
hooks_dir = self.install_dir / "hooks"
removed_count = 0
# Remove actual hook files
for filename in self.hook_files:
file_path = hooks_dir / filename
if self.file_manager.remove_file(file_path):
removed_count += 1
self.logger.debug(f"Removed {filename}")
# Remove placeholder file
placeholder_path = hooks_dir / "PLACEHOLDER.py"
if self.file_manager.remove_file(placeholder_path):
removed_count += 1
self.logger.debug("Removed hooks placeholder")
# Remove hooks directory if empty
try:
if hooks_dir.exists():
remaining_files = list(hooks_dir.iterdir())
if not remaining_files:
hooks_dir.rmdir()
self.logger.debug("Removed empty hooks directory")
except Exception as e:
self.logger.warning(f"Could not remove hooks directory: {e}")
# Update settings.json to remove hooks component and configuration
try:
if self.settings_manager.is_component_installed("hooks"):
self.settings_manager.remove_component_registration("hooks")
# Also remove hooks configuration section if it exists
settings = self.settings_manager.load_settings()
if "hooks" in settings:
del settings["hooks"]
self.settings_manager.save_settings(settings)
self.logger.info("Removed hooks component and configuration from settings.json")
except Exception as e:
self.logger.warning(f"Could not update settings.json: {e}")
self.logger.success(f"Hooks component uninstalled ({removed_count} files removed)")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during hooks uninstallation: {e}")
return False
def get_dependencies(self) -> List[str]:
"""Get dependencies"""
return ["core"]
def update(self, config: Dict[str, Any]) -> bool:
"""Update hooks component"""
try:
self.logger.info("Updating SuperClaude hooks component...")
# Check current version
current_version = self.settings_manager.get_component_version("hooks")
target_version = self.get_metadata()["version"]
if current_version == target_version:
self.logger.info(f"Hooks component already at version {target_version}")
return True
self.logger.info(f"Updating hooks component from {current_version} to {target_version}")
# Create backup of existing hook files
hooks_dir = self.install_dir / "hooks"
backup_files = []
if hooks_dir.exists():
for filename in self.hook_files + ["PLACEHOLDER.py"]:
file_path = hooks_dir / filename
if file_path.exists():
backup_path = self.file_manager.backup_file(file_path)
if backup_path:
backup_files.append(backup_path)
self.logger.debug(f"Backed up {filename}")
# Perform installation (overwrites existing files)
success = self.install(config)
if success:
# Remove backup files on successful update
for backup_path in backup_files:
try:
backup_path.unlink()
except Exception:
pass # Ignore cleanup errors
self.logger.success(f"Hooks component updated to version {target_version}")
else:
# Restore from backup on failure
self.logger.warning("Update failed, restoring from backup...")
for backup_path in backup_files:
try:
original_path = backup_path.with_suffix('')
backup_path.rename(original_path)
self.logger.debug(f"Restored {original_path.name}")
except Exception as e:
self.logger.error(f"Could not restore {backup_path}: {e}")
return success
except Exception as e:
self.logger.exception(f"Unexpected error during hooks update: {e}")
return False
def validate_installation(self) -> Tuple[bool, List[str]]:
"""Validate hooks component installation"""
errors = []
# Check if hooks directory exists
hooks_dir = self.install_dir / "hooks"
if not hooks_dir.exists():
errors.append("Hooks directory not found")
return False, errors
# Check settings.json registration
if not self.settings_manager.is_component_installed("hooks"):
errors.append("Hooks component not registered in settings.json")
else:
# Check version matches
installed_version = self.settings_manager.get_component_version("hooks")
expected_version = self.get_metadata()["version"]
if installed_version != expected_version:
errors.append(f"Version mismatch: installed {installed_version}, expected {expected_version}")
# Check if we have either actual hooks or placeholder
has_placeholder = (hooks_dir / "PLACEHOLDER.py").exists()
has_actual_hooks = any((hooks_dir / filename).exists() for filename in self.hook_files)
if not has_placeholder and not has_actual_hooks:
errors.append("No hook files or placeholder found")
return len(errors) == 0, errors
def _get_source_dir(self) -> Path:
"""Get source directory for hook files"""
# Assume we're in SuperClaude/setup/components/hooks.py
# and hook files are in SuperClaude/SuperClaude/Hooks/
project_root = Path(__file__).parent.parent.parent
return project_root / "SuperClaude" / "Hooks"
def get_size_estimate(self) -> int:
"""Get estimated installation size"""
# Estimate based on placeholder or actual files
source_dir = self._get_source_dir()
total_size = 0
if source_dir.exists():
for filename in self.hook_files:
file_path = source_dir / filename
if file_path.exists():
total_size += file_path.stat().st_size
# Add placeholder overhead or minimum size
total_size = max(total_size, 10240) # At least 10KB
return total_size
def get_installation_summary(self) -> Dict[str, Any]:
"""Get installation summary"""
source_dir = self._get_source_dir()
status = "placeholder" if not source_dir.exists() else "implemented"
return {
"component": self.get_metadata()["name"],
"version": self.get_metadata()["version"],
"status": status,
"hook_files": self.hook_files if source_dir.exists() else ["PLACEHOLDER.py"],
"estimated_size": self.get_size_estimate(),
"install_directory": str(self.install_dir / "hooks"),
"dependencies": self.get_dependencies()
}

470
setup/components/mcp.py Normal file
View File

@@ -0,0 +1,470 @@
"""
MCP component for MCP server integration
"""
import subprocess
import json
from typing import Dict, List, Tuple, Any
from pathlib import Path
from ..base.component import Component
from ..core.settings_manager import SettingsManager
from ..utils.logger import get_logger
from ..utils.ui import confirm, display_info, display_warning
class MCPComponent(Component):
"""MCP servers integration component"""
def __init__(self, install_dir: Path = None):
"""Initialize MCP component"""
super().__init__(install_dir)
self.logger = get_logger()
self.settings_manager = SettingsManager(self.install_dir)
# Define MCP servers to install
self.mcp_servers = {
"sequential-thinking": {
"name": "sequential-thinking",
"description": "Multi-step problem solving and systematic analysis",
"npm_package": "@modelcontextprotocol/server-sequential-thinking",
"required": True
},
"context7": {
"name": "context7",
"description": "Official library documentation and code examples",
"npm_package": "@context7/mcp",
"required": True
},
"magic": {
"name": "magic",
"description": "Modern UI component generation and design systems",
"npm_package": "@21st/mcp",
"required": False,
"api_key_env": "TWENTYFIRST_API_KEY",
"api_key_description": "21st.dev API key for UI component generation"
},
"playwright": {
"name": "playwright",
"description": "Cross-browser E2E testing and automation",
"npm_package": "@modelcontextprotocol/server-playwright",
"required": False
}
}
def get_metadata(self) -> Dict[str, str]:
"""Get component metadata"""
return {
"name": "mcp",
"version": "3.0.0",
"description": "MCP server integration (Context7, Sequential, Magic, Playwright)",
"category": "integration"
}
def validate_prerequisites(self) -> Tuple[bool, List[str]]:
"""Check prerequisites"""
errors = []
# Check if Node.js is available
try:
result = subprocess.run(
["node", "--version"],
capture_output=True,
text=True,
timeout=10
)
if result.returncode != 0:
errors.append("Node.js not found - required for MCP servers")
else:
version = result.stdout.strip()
self.logger.debug(f"Found Node.js {version}")
# Check version (require 18+)
try:
version_num = int(version.lstrip('v').split('.')[0])
if version_num < 18:
errors.append(f"Node.js version {version} found, but version 18+ required")
except:
self.logger.warning(f"Could not parse Node.js version: {version}")
except (subprocess.TimeoutExpired, FileNotFoundError):
errors.append("Node.js not found - required for MCP servers")
# Check if Claude CLI is available
try:
result = subprocess.run(
["claude", "--version"],
capture_output=True,
text=True,
timeout=10
)
if result.returncode != 0:
errors.append("Claude CLI not found - required for MCP server management")
else:
version = result.stdout.strip()
self.logger.debug(f"Found Claude CLI {version}")
except (subprocess.TimeoutExpired, FileNotFoundError):
errors.append("Claude CLI not found - required for MCP server management")
# Check if npm is available
try:
result = subprocess.run(
["npm", "--version"],
capture_output=True,
text=True,
timeout=10
)
if result.returncode != 0:
errors.append("npm not found - required for MCP server installation")
else:
version = result.stdout.strip()
self.logger.debug(f"Found npm {version}")
except (subprocess.TimeoutExpired, FileNotFoundError):
errors.append("npm not found - required for MCP server installation")
return len(errors) == 0, errors
def get_files_to_install(self) -> List[Tuple[Path, Path]]:
"""Get files to install (none for MCP component)"""
return []
def get_settings_modifications(self) -> Dict[str, Any]:
"""Get settings modifications"""
return {
"components": {
"mcp": {
"version": "3.0.0",
"installed": True,
"servers_count": len(self.mcp_servers)
}
},
"mcp": {
"enabled": True,
"servers": list(self.mcp_servers.keys()),
"auto_update": False
}
}
def _check_mcp_server_installed(self, server_name: str) -> bool:
"""Check if MCP server is already installed"""
try:
result = subprocess.run(
["claude", "mcp", "list"],
capture_output=True,
text=True,
timeout=15
)
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 _install_mcp_server(self, server_info: Dict[str, Any], config: Dict[str, Any]) -> bool:
"""Install a single MCP server"""
server_name = server_info["name"]
npm_package = server_info["npm_package"]
try:
self.logger.info(f"Installing MCP server: {server_name}")
# Check if already installed
if self._check_mcp_server_installed(server_name):
self.logger.info(f"MCP server {server_name} already installed")
return True
# Handle API key requirements
if "api_key_env" in server_info:
api_key_env = server_info["api_key_env"]
api_key_desc = server_info.get("api_key_description", f"API key for {server_name}")
if not config.get("dry_run", False):
display_info(f"MCP server '{server_name}' requires an API key")
display_info(f"Environment variable: {api_key_env}")
display_info(f"Description: {api_key_desc}")
# Check if API key is already set
import os
if not os.getenv(api_key_env):
display_warning(f"API key {api_key_env} not found in environment")
self.logger.warning(f"Proceeding without {api_key_env} - server may not function properly")
# Install using Claude CLI
if config.get("dry_run", False):
self.logger.info(f"Would install MCP server: claude mcp add {npm_package}")
return True
self.logger.debug(f"Running: claude mcp add {npm_package}")
result = subprocess.run(
["claude", "mcp", "add", npm_package],
capture_output=True,
text=True,
timeout=120 # 2 minutes timeout for installation
)
if result.returncode == 0:
self.logger.success(f"Successfully installed MCP server: {server_name}")
return True
else:
error_msg = result.stderr.strip() if result.stderr else "Unknown error"
self.logger.error(f"Failed to install MCP server {server_name}: {error_msg}")
return False
except subprocess.TimeoutExpired:
self.logger.error(f"Timeout installing MCP server {server_name}")
return False
except Exception as e:
self.logger.error(f"Error installing MCP server {server_name}: {e}")
return False
def _uninstall_mcp_server(self, server_name: str) -> bool:
"""Uninstall a single MCP server"""
try:
self.logger.info(f"Uninstalling MCP server: {server_name}")
# Check if installed
if not self._check_mcp_server_installed(server_name):
self.logger.info(f"MCP server {server_name} not installed")
return True
self.logger.debug(f"Running: claude mcp remove {server_name}")
result = subprocess.run(
["claude", "mcp", "remove", server_name],
capture_output=True,
text=True,
timeout=60
)
if result.returncode == 0:
self.logger.success(f"Successfully uninstalled MCP server: {server_name}")
return True
else:
error_msg = result.stderr.strip() if result.stderr else "Unknown error"
self.logger.error(f"Failed to uninstall MCP server {server_name}: {error_msg}")
return False
except subprocess.TimeoutExpired:
self.logger.error(f"Timeout uninstalling MCP server {server_name}")
return False
except Exception as e:
self.logger.error(f"Error uninstalling MCP server {server_name}: {e}")
return False
def install(self, config: Dict[str, Any]) -> bool:
"""Install MCP component"""
try:
self.logger.info("Installing SuperClaude MCP servers...")
# Validate prerequisites
success, errors = self.validate_prerequisites()
if not success:
for error in errors:
self.logger.error(error)
return False
# Install each MCP server
installed_count = 0
failed_servers = []
for server_name, server_info in self.mcp_servers.items():
if self._install_mcp_server(server_info, config):
installed_count += 1
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
# Update settings.json
try:
settings_mods = self.get_settings_modifications()
self.settings_manager.update_settings(settings_mods)
self.logger.info("Updated settings.json with MCP component registration")
except Exception as e:
self.logger.error(f"Failed to update settings.json: {e}")
return False
# Verify installation
if not config.get("dry_run", False):
self.logger.info("Verifying MCP server installation...")
try:
result = subprocess.run(
["claude", "mcp", "list"],
capture_output=True,
text=True,
timeout=15
)
if result.returncode == 0:
self.logger.debug("MCP servers list:")
for line in result.stdout.strip().split('\n'):
if line.strip():
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)")
else:
self.logger.success(f"MCP component installed successfully ({installed_count} servers)")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during MCP installation: {e}")
return False
def uninstall(self) -> bool:
"""Uninstall MCP component"""
try:
self.logger.info("Uninstalling SuperClaude MCP servers...")
# Uninstall each MCP server
uninstalled_count = 0
for server_name in self.mcp_servers.keys():
if self._uninstall_mcp_server(server_name):
uninstalled_count += 1
# Update settings.json to remove MCP component
try:
if self.settings_manager.is_component_installed("mcp"):
self.settings_manager.remove_component_registration("mcp")
self.logger.info("Removed MCP component from settings.json")
except Exception as e:
self.logger.warning(f"Could not update settings.json: {e}")
self.logger.success(f"MCP component uninstalled ({uninstalled_count} servers removed)")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during MCP uninstallation: {e}")
return False
def get_dependencies(self) -> List[str]:
"""Get dependencies"""
return ["core"]
def update(self, config: Dict[str, Any]) -> bool:
"""Update MCP component"""
try:
self.logger.info("Updating SuperClaude MCP servers...")
# Check current version
current_version = self.settings_manager.get_component_version("mcp")
target_version = self.get_metadata()["version"]
if current_version == target_version:
self.logger.info(f"MCP component already at version {target_version}")
return True
self.logger.info(f"Updating MCP component from {current_version} to {target_version}")
# For MCP servers, update means reinstall to get latest versions
updated_count = 0
failed_servers = []
for server_name, server_info in self.mcp_servers.items():
try:
# Uninstall old version
if self._check_mcp_server_installed(server_name):
self._uninstall_mcp_server(server_name)
# Install new version
if self._install_mcp_server(server_info, config):
updated_count += 1
else:
failed_servers.append(server_name)
except Exception as e:
self.logger.error(f"Error updating MCP server {server_name}: {e}")
failed_servers.append(server_name)
# Update settings
try:
settings_mods = self.get_settings_modifications()
self.settings_manager.update_settings(settings_mods)
except Exception as e:
self.logger.warning(f"Could not update settings.json: {e}")
if failed_servers:
self.logger.warning(f"Some MCP servers failed to update: {failed_servers}")
return False
else:
self.logger.success(f"MCP component updated to version {target_version}")
return True
except Exception as e:
self.logger.exception(f"Unexpected error during MCP update: {e}")
return False
def validate_installation(self) -> Tuple[bool, List[str]]:
"""Validate MCP component installation"""
errors = []
# Check settings.json registration
if not self.settings_manager.is_component_installed("mcp"):
errors.append("MCP component not registered in settings.json")
return False, errors
# Check version matches
installed_version = self.settings_manager.get_component_version("mcp")
expected_version = self.get_metadata()["version"]
if installed_version != expected_version:
errors.append(f"Version mismatch: installed {installed_version}, expected {expected_version}")
# Check if Claude CLI is available
try:
result = subprocess.run(
["claude", "mcp", "list"],
capture_output=True,
text=True,
timeout=15
)
if result.returncode != 0:
errors.append("Could not communicate with Claude CLI for MCP server verification")
else:
# Check if required servers are installed
output = result.stdout.lower()
for server_name, server_info in self.mcp_servers.items():
if server_info.get("required", False):
if server_name.lower() not in output:
errors.append(f"Required MCP server not found: {server_name}")
except Exception as e:
errors.append(f"Could not verify MCP server installation: {e}")
return len(errors) == 0, errors
def get_size_estimate(self) -> int:
"""Get estimated installation size"""
# MCP servers are installed via npm, estimate based on typical sizes
base_size = 50 * 1024 * 1024 # ~50MB for all servers combined
return base_size
def get_installation_summary(self) -> Dict[str, Any]:
"""Get installation summary"""
return {
"component": self.get_metadata()["name"],
"version": self.get_metadata()["version"],
"servers_count": len(self.mcp_servers),
"mcp_servers": list(self.mcp_servers.keys()),
"estimated_size": self.get_size_estimate(),
"dependencies": self.get_dependencies(),
"required_tools": ["node", "npm", "claude"]
}