devsync 0.5.5__py3-none-any.whl

aiconfigkit/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running instructionkit as a module."""
+
+from aiconfigkit.cli.main import app
+
+if __name__ == "__main__":
+    app()

aiconfigkit/ai_tools/base.py

@@ -0,0 +1,236 @@
+"""Base interface for AI coding tool integrations."""
+
+import os
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+
+from aiconfigkit.core.models import AIToolType, InstallationScope, Instruction
+
+
+class AITool(ABC):
+    """
+    Abstract base class for AI coding tool integrations.
+
+    Each AI tool (Cline, Cursor, Copilot, Kiro, Roo Code, Winsurf, Claude) implements this interface
+    to provide tool-specific installation logic.
+    """
+
+    @property
+    @abstractmethod
+    def tool_type(self) -> AIToolType:
+        """Return the AI tool type identifier."""
+        pass
+
+    @property
+    @abstractmethod
+    def tool_name(self) -> str:
+        """Return human-readable tool name."""
+        pass
+
+    @abstractmethod
+    def is_installed(self) -> bool:
+        """
+        Check if this AI tool is installed on the system.
+
+        Returns:
+            True if tool is detected, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_instructions_directory(self) -> Path:
+        """
+        Get the directory where instructions should be installed.
+
+        Returns:
+            Path to instructions directory
+
+        Raises:
+            FileNotFoundError: If tool is not installed
+        """
+        pass
+
+    @abstractmethod
+    def get_instruction_file_extension(self) -> str:
+        """
+        Get the file extension for instructions (e.g., '.md', '.txt').
+
+        Returns:
+            File extension including the dot
+        """
+        pass
+
+    @abstractmethod
+    def get_project_instructions_directory(self, project_root: Path) -> Path:
+        """
+        Get the directory where project-specific instructions should be installed.
+
+        Args:
+            project_root: Path to the project root directory
+
+        Returns:
+            Path to project instructions directory
+        """
+        pass
+
+    def get_mcp_config_path(self) -> Path:
+        """
+        Get the path to the MCP configuration file for this AI tool.
+
+        This is an optional method - tools that support MCP server configuration
+        should override this method.
+
+        Returns:
+            Path to MCP configuration file
+
+        Raises:
+            NotImplementedError: If tool doesn't support MCP configuration
+        """
+        raise NotImplementedError(f"{self.tool_name} does not support MCP server configuration")
+
+    def get_instruction_path(
+        self,
+        instruction_name: str,
+        scope: InstallationScope = InstallationScope.GLOBAL,
+        project_root: Optional[Path] = None,
+    ) -> Path:
+        """
+        Get the full path where an instruction file should be installed.
+
+        Args:
+            instruction_name: Name of the instruction
+            scope: Installation scope (global or project)
+            project_root: Project root path (required if scope is PROJECT)
+
+        Returns:
+            Full path to instruction file
+
+        Raises:
+            ValueError: If scope is PROJECT but project_root is None
+        """
+        if scope == InstallationScope.PROJECT:
+            if project_root is None:
+                raise ValueError("project_root is required for PROJECT scope")
+            directory = self.get_project_instructions_directory(project_root)
+        else:
+            directory = self.get_instructions_directory()
+
+        extension = self.get_instruction_file_extension()
+        filename = f"{instruction_name}{extension}"
+        return directory / filename
+
+    def instruction_exists(
+        self,
+        instruction_name: str,
+        scope: InstallationScope = InstallationScope.GLOBAL,
+        project_root: Optional[Path] = None,
+    ) -> bool:
+        """
+        Check if an instruction is already installed.
+
+        Args:
+            instruction_name: Name of the instruction
+            scope: Installation scope (global or project)
+            project_root: Project root path (required if scope is PROJECT)
+
+        Returns:
+            True if instruction file exists
+        """
+        try:
+            path = self.get_instruction_path(instruction_name, scope, project_root)
+            return path.exists()
+        except (FileNotFoundError, ValueError):
+            return False
+
+    def install_instruction(
+        self,
+        instruction: Instruction,
+        overwrite: bool = False,
+        scope: InstallationScope = InstallationScope.GLOBAL,
+        project_root: Optional[Path] = None,
+    ) -> Path:
+        """
+        Install an instruction to this AI tool.
+
+        Args:
+            instruction: Instruction to install
+            overwrite: Whether to overwrite existing file
+            scope: Installation scope (global or project)
+            project_root: Project root path (required if scope is PROJECT)
+
+        Returns:
+            Path where instruction was installed
+
+        Raises:
+            FileExistsError: If instruction exists and overwrite=False
+            FileNotFoundError: If tool is not installed
+            ValueError: If scope is PROJECT but project_root is None
+        """
+        path = self.get_instruction_path(instruction.name, scope, project_root)
+
+        if path.exists() and not overwrite:
+            raise FileExistsError(f"Instruction already exists: {path}")
+
+        # Ensure directory exists
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write instruction content
+        path.write_text(instruction.content, encoding="utf-8")
+
+        return path
+
+    def uninstall_instruction(
+        self,
+        instruction_name: str,
+        scope: InstallationScope = InstallationScope.GLOBAL,
+        project_root: Optional[Path] = None,
+    ) -> bool:
+        """
+        Uninstall an instruction from this AI tool.
+
+        Args:
+            instruction_name: Name of instruction to remove
+            scope: Installation scope (global or project)
+            project_root: Project root path (required if scope is PROJECT)
+
+        Returns:
+            True if file was removed, False if it didn't exist
+        """
+        try:
+            path = self.get_instruction_path(instruction_name, scope, project_root)
+            if path.exists():
+                path.unlink()
+                return True
+            return False
+        except (FileNotFoundError, ValueError):
+            return False
+
+    def validate_installation(self) -> Optional[str]:
+        """
+        Validate that tool installation is correct and accessible.
+
+        Returns:
+            None if valid, error message if invalid
+        """
+        if not self.is_installed():
+            return f"{self.tool_name} is not installed or not found"
+
+        try:
+            directory = self.get_instructions_directory()
+            if not directory.exists():
+                # Try to create it
+                directory.mkdir(parents=True, exist_ok=True)
+
+            # Check write permissions
+            if not os.access(directory, os.W_OK):
+                return f"No write permission for {directory}"
+
+        except Exception as e:
+            return f"Error accessing {self.tool_name} directory: {str(e)}"
+
+        return None
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"<{self.__class__.__name__} tool_type={self.tool_type.value}>"

aiconfigkit/ai_tools/capability_registry.py

@@ -0,0 +1,262 @@
+"""IDE capability registry for package component support."""
+
+from dataclasses import dataclass
+
+from aiconfigkit.core.models import AIToolType, ComponentType
+
+
+@dataclass
+class IDECapability:
+    """
+    Defines what component types an IDE supports.
+
+    Tracks which package components (instructions, MCP servers, hooks, etc.)
+    can be installed to each AI coding tool.
+    """
+
+    tool_type: AIToolType
+    tool_name: str
+    supported_components: set[ComponentType]
+    instructions_directory: str
+    instruction_file_extension: str
+    supports_project_scope: bool = True
+    supports_global_scope: bool = False
+    mcp_config_path: str | None = None
+    mcp_project_config_path: str | None = None  # Project-level MCP config
+    hooks_directory: str | None = None
+    commands_directory: str | None = None
+    skills_directory: str | None = None  # Claude skills
+    workflows_directory: str | None = None  # Windsurf workflows
+    memory_file_name: str | None = None  # CLAUDE.md
+    notes: str = ""
+
+    def supports_component(self, component_type: ComponentType) -> bool:
+        """
+        Check if IDE supports a specific component type.
+
+        Args:
+            component_type: Component type to check
+
+        Returns:
+            True if supported, False otherwise
+        """
+        return component_type in self.supported_components
+
+
+# IDE Capability Registry
+# Maps each AI tool to its supported component types and installation paths
+
+CAPABILITY_REGISTRY: dict[AIToolType, IDECapability] = {
+    AIToolType.CURSOR: IDECapability(
+        tool_type=AIToolType.CURSOR,
+        tool_name="Cursor",
+        supported_components={
+            ComponentType.INSTRUCTION,
+            ComponentType.MCP_SERVER,
+            ComponentType.RESOURCE,
+        },
+        instructions_directory=".cursor/rules/",
+        instruction_file_extension=".mdc",
+        supports_project_scope=True,
+        supports_global_scope=True,
+        mcp_config_path="~/.cursor/mcp.json",
+        mcp_project_config_path=".cursor/mcp.json",
+        hooks_directory=None,  # Hooks not supported
+        commands_directory=None,  # Commands not supported
+        notes=(
+            "Cursor uses .mdc (markdown with metadata) files in .cursor/rules/. "
+            "MCP servers configured via ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). "
+            "Supports up to 40 MCP tools. Resources not yet supported in MCP."
+        ),
+    ),
+    AIToolType.CLAUDE: IDECapability(
+        tool_type=AIToolType.CLAUDE,
+        tool_name="Claude Code",
+        supported_components={
+            ComponentType.INSTRUCTION,
+            ComponentType.MCP_SERVER,
+            ComponentType.HOOK,
+            ComponentType.COMMAND,
+            ComponentType.SKILL,
+            ComponentType.MEMORY_FILE,
+            ComponentType.RESOURCE,
+        },
+        instructions_directory=".claude/rules/",
+        instruction_file_extension=".md",
+        supports_project_scope=True,
+        supports_global_scope=False,
+        mcp_config_path="~/.claude/settings.json",
+        mcp_project_config_path=".claude/settings.local.json",
+        hooks_directory=".claude/hooks/",
+        commands_directory=".claude/commands/",
+        skills_directory=".claude/skills/",
+        memory_file_name="CLAUDE.md",
+        notes=(
+            "Claude Code uses .md files in .claude/rules/. "
+            "Full support for MCP servers, hooks, slash commands, and skills. "
+            "CLAUDE.md files persist context across sessions."
+        ),
+    ),
+    AIToolType.WINSURF: IDECapability(
+        tool_type=AIToolType.WINSURF,
+        tool_name="Windsurf",
+        supported_components={
+            ComponentType.INSTRUCTION,
+            ComponentType.MCP_SERVER,
+            ComponentType.WORKFLOW,
+            ComponentType.RESOURCE,
+        },
+        instructions_directory=".windsurf/rules/",
+        instruction_file_extension=".md",
+        supports_project_scope=True,
+        supports_global_scope=True,
+        mcp_config_path="~/.codeium/windsurf/mcp_config.json",
+        mcp_project_config_path=None,  # Windsurf uses global MCP config only
+        hooks_directory=None,  # Hooks not supported
+        commands_directory=None,  # Commands not supported
+        workflows_directory=".windsurf/workflows/",
+        notes=(
+            "Windsurf uses .md files in .windsurf/rules/ with 4 activation modes. "
+            "MCP servers configured via ~/.codeium/windsurf/mcp_config.json. "
+            "Supports workflows in .windsurf/workflows/. Limit of 100 MCP tools."
+        ),
+    ),
+    AIToolType.KIRO: IDECapability(
+        tool_type=AIToolType.KIRO,
+        tool_name="Kiro",
+        supported_components={
+            ComponentType.INSTRUCTION,
+            ComponentType.RESOURCE,
+        },
+        instructions_directory=".kiro/steering/",
+        instruction_file_extension=".md",
+        supports_project_scope=True,
+        supports_global_scope=False,
+        mcp_config_path=None,  # Kiro uses .kiro/settings/mcp.json but not yet supported
+        mcp_project_config_path=None,
+        hooks_directory=None,  # Kiro hooks use .kiro.hook JSON format, not yet supported
+        commands_directory=None,
+        notes=(
+            "Kiro uses .md files in .kiro/steering/ with optional YAML front matter "
+            "for inclusion modes (always, fileMatch, manual, auto). "
+            "MCP and hooks support deferred to future release."
+        ),
+    ),
+    AIToolType.CLINE: IDECapability(
+        tool_type=AIToolType.CLINE,
+        tool_name="Cline",
+        supported_components={
+            ComponentType.INSTRUCTION,
+            ComponentType.RESOURCE,
+        },
+        instructions_directory=".clinerules/",
+        instruction_file_extension=".md",
+        supports_project_scope=True,
+        supports_global_scope=False,
+        mcp_config_path=None,  # Cline MCP is global-only via cline_mcp_settings.json in VS Code globalStorage
+        mcp_project_config_path=None,
+        hooks_directory=None,
+        commands_directory=None,
+        notes=(
+            "Cline uses .md files in .clinerules/ directory (recursive). "
+            "Supports optional YAML frontmatter with paths: for conditional activation. "
+            "MCP configured globally via cline_mcp_settings.json, no project-level MCP support."
+        ),
+    ),
+    AIToolType.ROO: IDECapability(
+        tool_type=AIToolType.ROO,
+        tool_name="Roo Code",
+        supported_components={
+            ComponentType.INSTRUCTION,
+            ComponentType.MCP_SERVER,
+            ComponentType.COMMAND,
+            ComponentType.RESOURCE,
+        },
+        instructions_directory=".roo/rules/",
+        instruction_file_extension=".md",
+        supports_project_scope=True,
+        supports_global_scope=True,
+        mcp_config_path=None,  # Global MCP via globalStorage cline_mcp_settings.json
+        mcp_project_config_path=".roo/mcp.json",
+        hooks_directory=None,  # Hooks not supported
+        commands_directory=".roo/commands/",
+        notes=(
+            "Roo Code uses .md files in .roo/rules/ directory (recursive). "
+            "Mode-specific rules in .roo/rules-{mode-slug}/. "
+            "MCP configured via .roo/mcp.json (project) or globalStorage (global). "
+            "Slash commands in .roo/commands/. Global rules at ~/.roo/rules/."
+        ),
+    ),
+    AIToolType.COPILOT: IDECapability(
+        tool_type=AIToolType.COPILOT,
+        tool_name="GitHub Copilot",
+        supported_components={
+            ComponentType.INSTRUCTION,
+            ComponentType.MCP_SERVER,
+        },
+        instructions_directory=".github/instructions/",
+        instruction_file_extension=".instructions.md",
+        supports_project_scope=True,
+        supports_global_scope=True,
+        mcp_config_path="~/.vscode/mcp.json",  # User-level MCP config
+        mcp_project_config_path=".vscode/mcp.json",  # Workspace-level MCP config
+        hooks_directory=None,  # Hooks not supported
+        commands_directory=None,  # Commands not supported
+        notes=(
+            "GitHub Copilot uses .github/copilot-instructions.md (main) and "
+            ".github/instructions/**/*.instructions.md (file-specific with globs). "
+            "MCP servers configured via .vscode/mcp.json. Limit of 128 tools."
+        ),
+    ),
+}
+
+
+def get_capability(tool_type: AIToolType) -> IDECapability:
+    """
+    Get capability information for an IDE.
+
+    Args:
+        tool_type: AI tool type
+
+    Returns:
+        IDECapability for the tool
+
+    Raises:
+        KeyError: If tool type is not in registry
+    """
+    return CAPABILITY_REGISTRY[tool_type]
+
+
+def get_supported_tools_for_component(component_type: ComponentType) -> list[AIToolType]:
+    """
+    Get list of IDEs that support a specific component type.
+
+    Args:
+        component_type: Component type to check
+
+    Returns:
+        List of AI tool types that support this component
+    """
+    supported_tools = []
+    for tool_type, capability in CAPABILITY_REGISTRY.items():
+        if capability.supports_component(component_type):
+            supported_tools.append(tool_type)
+    return supported_tools
+
+
+def validate_component_support(tool_type: AIToolType, component_type: ComponentType) -> bool:
+    """
+    Validate that an IDE supports a component type.
+
+    Args:
+        tool_type: AI tool type
+        component_type: Component type to validate
+
+    Returns:
+        True if supported, False otherwise
+    """
+    try:
+        capability = get_capability(tool_type)
+        return capability.supports_component(component_type)
+    except KeyError:
+        return False

aiconfigkit/ai_tools/claude.py

@@ -0,0 +1,91 @@
+"""Claude Code AI tool integration."""
+
+from pathlib import Path
+
+from aiconfigkit.ai_tools.base import AITool
+from aiconfigkit.core.models import AIToolType
+from aiconfigkit.utils.paths import get_claude_config_dir
+
+
+class ClaudeTool(AITool):
+    """Integration for Claude Code AI coding tool."""
+
+    @property
+    def tool_type(self) -> AIToolType:
+        """Return the AI tool type identifier."""
+        return AIToolType.CLAUDE
+
+    @property
+    def tool_name(self) -> str:
+        """Return human-readable tool name."""
+        return "Claude Code"
+
+    def is_installed(self) -> bool:
+        """
+        Check if Claude Code is installed on the system.
+
+        Checks for existence of Claude configuration directory.
+
+        Returns:
+            True if Claude Code is detected
+        """
+        try:
+            config_dir = get_claude_config_dir()
+            # Check if parent directory exists
+            # Claude Code config dir structure: ~/.claude/rules/
+            claude_base = config_dir.parent
+            return claude_base.exists()
+        except Exception:
+            return False
+
+    def get_instructions_directory(self) -> Path:
+        """
+        Get the directory where Claude Code instructions should be installed.
+
+        Note: Global installation is not supported. Claude Code supports both
+        single-file (~/.claude/rules.md) and multi-file approaches, but for
+        consistency with our multi-file installation pattern, we only support
+        project-level installations.
+
+        Returns:
+            Path to Claude Code instructions directory
+
+        Raises:
+            NotImplementedError: Global installation not supported for Claude Code
+        """
+        raise NotImplementedError(
+            f"{self.tool_name} global installation is not supported. "
+            "Please use project-level installation instead (--scope project)."
+        )
+
+    def get_instruction_file_extension(self) -> str:
+        """
+        Get the file extension for Claude Code instructions.
+
+        Claude Code uses markdown (.md) files for rules.
+
+        Returns:
+            File extension including the dot
+        """
+        return ".md"
+
+    def get_project_instructions_directory(self, project_root: Path) -> Path:
+        """
+        Get the directory for project-specific Claude Code instructions.
+
+        Claude Code stores project-specific rules in .claude/rules/ directory
+        in the project root. It supports multiple .md files in this directory.
+
+        Reference:
+        - Recommended: .claude/rules/*.md (multiple files)
+        - Alternative: .claude/rules.md (single file, not used by this tool)
+
+        Args:
+            project_root: Path to the project root directory
+
+        Returns:
+            Path to project instructions directory (.claude/rules/)
+        """
+        instructions_dir = project_root / ".claude" / "rules"
+        instructions_dir.mkdir(parents=True, exist_ok=True)
+        return instructions_dir

aiconfigkit/ai_tools/claude_desktop.py

@@ -0,0 +1,97 @@
+"""Claude Desktop MCP integration."""
+
+from pathlib import Path
+
+from aiconfigkit.ai_tools.base import AITool
+from aiconfigkit.core.models import AIToolType
+from aiconfigkit.utils.paths import get_claude_desktop_config_path
+
+
+class ClaudeDesktopTool(AITool):
+    """Integration for Claude Desktop MCP server configuration."""
+
+    @property
+    def tool_type(self) -> AIToolType:
+        """Return the AI tool type identifier."""
+        return AIToolType.CLAUDE
+
+    @property
+    def tool_name(self) -> str:
+        """Return human-readable tool name."""
+        return "Claude Desktop"
+
+    def is_installed(self) -> bool:
+        """
+        Check if Claude Desktop is installed on the system.
+
+        Checks for existence of Claude Desktop config directory.
+
+        Returns:
+            True if Claude Desktop is detected
+        """
+        try:
+            config_path = get_claude_desktop_config_path()
+            # Check if parent directory exists (Claude Desktop install directory)
+            return config_path.parent.exists()
+        except Exception:
+            return False
+
+    def get_instructions_directory(self) -> Path:
+        """
+        Get the directory where Claude Desktop instructions should be installed.
+
+        Note: Claude Desktop doesn't use instruction files like Claude Code.
+        This method is not applicable for MCP configuration.
+
+        Returns:
+            Path to instructions directory
+
+        Raises:
+            NotImplementedError: Claude Desktop uses MCP config, not instruction files
+        """
+        raise NotImplementedError(
+            f"{self.tool_name} uses MCP configuration instead of instruction files. "
+            "Use get_mcp_config_path() instead."
+        )
+
+    def get_instruction_file_extension(self) -> str:
+        """
+        Get the file extension for Claude Desktop instructions.
+
+        Returns:
+            File extension including the dot
+
+        Raises:
+            NotImplementedError: Claude Desktop uses MCP config, not instruction files
+        """
+        raise NotImplementedError(f"{self.tool_name} uses MCP configuration instead of instruction files.")
+
+    def get_project_instructions_directory(self, project_root: Path) -> Path:
+        """
+        Get the directory for project-specific Claude Desktop instructions.
+
+        Args:
+            project_root: Path to the project root directory
+
+        Returns:
+            Path to project instructions directory
+
+        Raises:
+            NotImplementedError: Claude Desktop uses MCP config, not instruction files
+        """
+        raise NotImplementedError(f"{self.tool_name} uses MCP configuration instead of instruction files.")
+
+    def get_mcp_config_path(self) -> Path:
+        """
+        Get the path to the Claude Desktop MCP configuration file.
+
+        Claude Desktop stores MCP server configurations in claude_desktop_config.json.
+        The file location is platform-specific:
+        - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+        - Linux: ~/.config/Claude/claude_desktop_config.json
+        - Windows: %APPDATA%\\Claude\\claude_desktop_config.json
+
+        Returns:
+            Path to claude_desktop_config.json
+        """
+        return get_claude_desktop_config_path()