llm-ide-rules 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

llm_ide_rules/__init__.py

@@ -1,14 +1,20 @@
 """LLM Rules CLI package for managing IDE prompts and rules."""
 
+import os
+
+if "LOG_LEVEL" not in os.environ:
+    os.environ["LOG_LEVEL"] = "WARNING"
+
 import typer
 from typing_extensions import Annotated
 
 from llm_ide_rules.commands.explode import explode_main
-from llm_ide_rules.commands.implode import cursor, github, claude, gemini
+from llm_ide_rules.commands.implode import cursor, github, claude, gemini, opencode
 from llm_ide_rules.commands.download import download_main
 from llm_ide_rules.commands.delete import delete_main
+from llm_ide_rules.commands.mcp import mcp_app
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 app = typer.Typer(
     name="llm_ide_rules",
@@ -16,22 +22,60 @@ app = typer.Typer(
     no_args_is_help=True,
 )
 
+
+@app.callback()
+def main_callback(
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose", "-v", help="Enable verbose logging (sets LOG_LEVEL=DEBUG)"
+        ),
+    ] = False,
+):
+    """Global CLI options."""
+    if verbose:
+        os.environ["LOG_LEVEL"] = "DEBUG"
+        import structlog_config
+
+        structlog_config.configure_logger()
+
+
 # Add commands directly
-app.command("explode", help="Convert instruction file to separate rule files")(explode_main)
-app.command("download", help="Download LLM instruction files from GitHub repositories")(download_main)
+app.command("explode", help="Convert instruction file to separate rule files")(
+    explode_main
+)
+app.command("download", help="Download LLM instruction files from GitHub repositories")(
+    download_main
+)
 app.command("delete", help="Remove downloaded LLM instruction files")(delete_main)
 
 # Create implode sub-typer
 implode_app = typer.Typer(help="Bundle rule files into a single instruction file")
-implode_app.command("cursor", help="Bundle Cursor rules and commands into a single file")(cursor)
-implode_app.command("github", help="Bundle GitHub/Copilot instructions and prompts into a single file")(github)
-implode_app.command("claude", help="Bundle Claude Code commands into a single file")(claude)
-implode_app.command("gemini", help="Bundle Gemini CLI commands into a single file")(gemini)
+implode_app.command(
+    "cursor", help="Bundle Cursor rules and commands into a single file"
+)(cursor)
+implode_app.command(
+    "github", help="Bundle GitHub/Copilot instructions and prompts into a single file"
+)(github)
+implode_app.command("claude", help="Bundle Claude Code commands into a single file")(
+    claude
+)
+implode_app.command("gemini", help="Bundle Gemini CLI commands into a single file")(
+    gemini
+)
+implode_app.command("opencode", help="Bundle OpenCode commands into a single file")(
+    opencode
+)
 app.add_typer(implode_app, name="implode")
 
+# Add MCP configuration management
+app.add_typer(mcp_app, name="mcp")
+
+
 def main():
     """Main entry point for the CLI."""
     app()
 
+
 if __name__ == "__main__":
-    main()
+    main()

llm_ide_rules/__main__.py

@@ -3,4 +3,4 @@
 from llm_ide_rules import main
 
 if __name__ == "__main__":
-    main()
+    main()

llm_ide_rules/agents/__init__.py

@@ -0,0 +1,28 @@
+"""Agent registry for LLM IDE rules."""
+
+from llm_ide_rules.agents.base import BaseAgent
+from llm_ide_rules.agents.cursor import CursorAgent
+from llm_ide_rules.agents.github import GitHubAgent
+from llm_ide_rules.agents.claude import ClaudeAgent
+from llm_ide_rules.agents.gemini import GeminiAgent
+from llm_ide_rules.agents.opencode import OpenCodeAgent
+
+AGENTS: dict[str, type[BaseAgent]] = {
+    "cursor": CursorAgent,
+    "github": GitHubAgent,
+    "claude": ClaudeAgent,
+    "gemini": GeminiAgent,
+    "opencode": OpenCodeAgent,
+}
+
+
+def get_agent(name: str) -> BaseAgent:
+    """Get an agent instance by name."""
+    if name not in AGENTS:
+        raise ValueError(f"Unknown agent: {name}. Available: {list(AGENTS.keys())}")
+    return AGENTS[name]()
+
+
+def get_all_agents() -> list[BaseAgent]:
+    """Get instances of all registered agents."""
+    return [agent_cls() for agent_cls in AGENTS.values()]

llm_ide_rules/agents/base.py

@@ -0,0 +1,283 @@
+"""Base agent class and shared utilities for LLM IDE rules."""
+
+import json
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from llm_ide_rules.constants import header_to_filename
+from llm_ide_rules.mcp import McpServer
+
+
+class BaseAgent(ABC):
+    """Base class for all IDE agents."""
+
+    name: str
+    rules_dir: str | None = None
+    commands_dir: str | None = None
+    rule_extension: str | None = None
+    command_extension: str | None = None
+
+    mcp_global_path: str | None = None
+    mcp_project_path: str | None = None
+    mcp_root_key: str = "mcpServers"
+
+    @abstractmethod
+    def bundle_rules(
+        self, output_file: Path, section_globs: dict[str, str | None]
+    ) -> bool:
+        """Bundle rule files into a single output file."""
+        ...
+
+    @abstractmethod
+    def bundle_commands(
+        self, output_file: Path, section_globs: dict[str, str | None]
+    ) -> bool:
+        """Bundle command files into a single output file."""
+        ...
+
+    @abstractmethod
+    def write_rule(
+        self,
+        content_lines: list[str],
+        filename: str,
+        rules_dir: Path,
+        glob_pattern: str | None = None,
+    ) -> None:
+        """Write a single rule file."""
+        ...
+
+    @abstractmethod
+    def write_command(
+        self,
+        content_lines: list[str],
+        filename: str,
+        commands_dir: Path,
+        section_name: str | None = None,
+    ) -> None:
+        """Write a single command file."""
+        ...
+
+    def get_rules_path(self, base_dir: Path) -> Path:
+        """Get the full path to the rules directory."""
+        if not self.rules_dir:
+            raise NotImplementedError(f"{self.name} does not support rules")
+        return base_dir / self.rules_dir
+
+    def get_commands_path(self, base_dir: Path) -> Path:
+        """Get the full path to the commands directory."""
+        if not self.commands_dir:
+            raise NotImplementedError(f"{self.name} does not support commands")
+        return base_dir / self.commands_dir
+
+    def transform_mcp_server(self, server: McpServer) -> dict:
+        """Transform unified server to platform-specific format."""
+        if server.url:
+            result: dict = {"url": server.url}
+            if server.env:
+                result["env"] = server.env
+            return result
+
+        result: dict = {"command": server.command, "args": server.args or []}
+        if server.env:
+            result["env"] = server.env
+        return result
+
+    def reverse_transform_mcp_server(self, name: str, config: dict) -> McpServer:
+        """Transform platform config back to unified format."""
+        if "url" in config:
+            return McpServer(
+                url=config["url"],
+                env=config.get("env"),
+            )
+
+        return McpServer(
+            command=config["command"],
+            args=config.get("args", []),
+            env=config.get("env"),
+        )
+
+    def write_mcp_config(self, servers: dict, path: Path) -> None:
+        """Write MCP config to path."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        config = {self.mcp_root_key: servers}
+        path.write_text(json.dumps(config, indent=2))
+
+    def read_mcp_config(self, path: Path) -> dict | None:
+        """Read MCP config from path."""
+        if not path.exists():
+            return None
+
+        config = json.loads(path.read_text())
+        return config.get(self.mcp_root_key)
+
+
+def strip_yaml_frontmatter(text: str) -> str:
+    """Strip YAML frontmatter from text."""
+    lines = text.splitlines()
+    if lines and lines[0].strip() == "---":
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                return "\n".join(lines[i + 1 :]).lstrip("\n")
+    return text
+
+
+def strip_header(text: str) -> str:
+    """Remove the first markdown header (## Header) from text if present."""
+    lines = text.splitlines()
+    if lines and lines[0].startswith("## "):
+        remaining_lines = lines[1:]
+        while remaining_lines and not remaining_lines[0].strip():
+            remaining_lines = remaining_lines[1:]
+        return "\n".join(remaining_lines)
+    return text
+
+
+def strip_toml_metadata(text: str) -> str:
+    """Extract content from TOML prompt block (supports old [command] shell=... and new prompt=...)."""
+    import tomllib
+
+    try:
+        data = tomllib.loads(text)
+        # Check new format
+        if "prompt" in data:
+            return str(data["prompt"]).strip()
+        # Check legacy format
+        if (
+            "command" in data
+            and isinstance(data["command"], dict)
+            and "shell" in data["command"]
+        ):
+            return str(data["command"]["shell"]).strip()
+    except Exception:
+        pass
+
+    return text.strip()
+
+
+def get_ordered_files(
+    file_list: list[Path], section_globs_keys: list[str]
+) -> list[Path]:
+    """Order files based on section_globs key order, with unmapped files at the end."""
+    file_dict = {f.stem: f for f in file_list}
+    ordered_files = []
+
+    for section_name in section_globs_keys:
+        filename = header_to_filename(section_name)
+        if filename in file_dict:
+            ordered_files.append(file_dict[filename])
+            del file_dict[filename]
+
+    remaining_files = sorted(file_dict.values(), key=lambda p: p.name)
+    ordered_files.extend(remaining_files)
+
+    return ordered_files
+
+
+def get_ordered_files_github(
+    file_list: list[Path], section_globs_keys: list[str]
+) -> list[Path]:
+    """Order GitHub instruction files, handling .instructions suffix."""
+    file_dict = {}
+    for f in file_list:
+        base_stem = f.stem.replace(".instructions", "")
+        file_dict[base_stem] = f
+
+    ordered_files = []
+
+    for section_name in section_globs_keys:
+        filename = header_to_filename(section_name)
+        if filename in file_dict:
+            ordered_files.append(file_dict[filename])
+            del file_dict[filename]
+
+    remaining_files = sorted(file_dict.values(), key=lambda p: p.name)
+    ordered_files.extend(remaining_files)
+
+    return ordered_files
+
+
+def resolve_header_from_stem(stem: str, section_globs: dict[str, str | None]) -> str:
+    """Return the canonical header for a given filename stem.
+
+    Prefer exact header names from section_globs (preserves acronyms like FastAPI, TypeScript).
+    Fallback to title-casing the filename when not found in section_globs.
+    """
+    for section_name in section_globs.keys():
+        if header_to_filename(section_name) == stem:
+            return section_name
+
+    return stem.replace("-", " ").title()
+
+
+def trim_content(content_lines: list[str]) -> list[str]:
+    """Remove leading and trailing empty lines from content."""
+    start = 0
+    for i, line in enumerate(content_lines):
+        if line.strip():
+            start = i
+            break
+    else:
+        return []
+
+    end = len(content_lines)
+    for i in range(len(content_lines) - 1, -1, -1):
+        if content_lines[i].strip():
+            end = i + 1
+            break
+
+    return content_lines[start:end]
+
+
+def write_rule_file(path: Path, header_yaml: str, content_lines: list[str]) -> None:
+    """Write a rule file with front matter and content."""
+    trimmed_content = trim_content(content_lines)
+    output = header_yaml.strip() + "\n" + "".join(trimmed_content)
+    path.write_text(output)
+
+
+def replace_header_with_proper_casing(
+    content_lines: list[str], proper_header: str
+) -> list[str]:
+    """Replace the first header in content with the properly cased version."""
+    if not content_lines:
+        return content_lines
+
+    for i, line in enumerate(content_lines):
+        if line.startswith("## "):
+            content_lines[i] = f"## {proper_header}\n"
+            break
+
+    return content_lines
+
+
+def extract_description_and_filter_content(
+    content_lines: list[str], default_description: str
+) -> tuple[str, list[str]]:
+    """Extract description from first non-empty line that starts with 'Description:' and return filtered content."""
+    trimmed_content = trim_content(content_lines)
+    description = ""
+    description_line = None
+
+    for i, line in enumerate(trimmed_content):
+        stripped_line = line.strip()
+        if (
+            stripped_line
+            and not stripped_line.startswith("#")
+            and not stripped_line.startswith("##")
+        ):
+            if stripped_line.startswith("Description:"):
+                description = stripped_line[len("Description:") :].strip()
+                description_line = i
+                break
+            else:
+                break
+
+    if description and description_line is not None:
+        filtered_content = (
+            trimmed_content[:description_line] + trimmed_content[description_line + 1 :]
+        )
+        filtered_content = trim_content(filtered_content)
+    else:
+        filtered_content = trimmed_content
+
+    return description, filtered_content

llm_ide_rules/agents/claude.py

@@ -0,0 +1,92 @@
+"""Claude Code agent implementation."""
+
+from pathlib import Path
+
+from llm_ide_rules.agents.base import (
+    BaseAgent,
+    get_ordered_files,
+    resolve_header_from_stem,
+    trim_content,
+)
+
+
+class ClaudeAgent(BaseAgent):
+    """Agent for Claude Code."""
+
+    name = "claude"
+    rules_dir = None
+    commands_dir = ".claude/commands"
+    rule_extension = None
+    command_extension = ".md"
+
+    mcp_global_path = ".claude.json"
+    mcp_project_path = ".mcp.json"
+
+    def bundle_rules(
+        self, output_file: Path, section_globs: dict[str, str | None]
+    ) -> bool:
+        """Claude Code doesn't support rules, only commands."""
+        return False
+
+    def bundle_commands(
+        self, output_file: Path, section_globs: dict[str, str | None]
+    ) -> bool:
+        """Bundle Claude Code command files (.md) into a single output file."""
+        commands_dir = self.commands_dir
+        if not commands_dir:
+            return False
+
+        commands_path = output_file.parent / commands_dir
+        if not commands_path.exists():
+            return False
+
+        extension = self.command_extension
+        if not extension:
+            return False
+
+        command_files = list(commands_path.glob(f"*{extension}"))
+        if not command_files:
+            return False
+
+        ordered_commands = get_ordered_files(command_files, list(section_globs.keys()))
+
+        content_parts: list[str] = []
+        for command_file in ordered_commands:
+            content = command_file.read_text().strip()
+            if not content:
+                continue
+
+            header = resolve_header_from_stem(command_file.stem, section_globs)
+            content_parts.append(f"## {header}\n\n")
+            content_parts.append(content)
+            content_parts.append("\n\n")
+
+        if not content_parts:
+            return False
+
+        output_file.write_text("".join(content_parts))
+        return True
+
+    def write_rule(
+        self,
+        content_lines: list[str],
+        filename: str,
+        rules_dir: Path,
+        glob_pattern: str | None = None,
+    ) -> None:
+        """Claude Code doesn't support rules."""
+        pass
+
+    def write_command(
+        self,
+        content_lines: list[str],
+        filename: str,
+        commands_dir: Path,
+        section_name: str | None = None,
+    ) -> None:
+        """Write a Claude Code command file (.md) - plain markdown, no frontmatter."""
+        extension = self.command_extension or ".md"
+        filepath = commands_dir / f"{filename}{extension}"
+
+        trimmed = trim_content(content_lines)
+        filepath.write_text("".join(trimmed))

llm_ide_rules/agents/cursor.py

@@ -0,0 +1,178 @@
+"""Cursor IDE agent implementation."""
+
+from pathlib import Path
+
+from llm_ide_rules.agents.base import (
+    BaseAgent,
+    get_ordered_files,
+    resolve_header_from_stem,
+    strip_yaml_frontmatter,
+    strip_header,
+    trim_content,
+    write_rule_file,
+    extract_description_and_filter_content,
+)
+
+
+class CursorAgent(BaseAgent):
+    """Agent for Cursor IDE."""
+
+    name = "cursor"
+    rules_dir = ".cursor/rules"
+    commands_dir = ".cursor/commands"
+    rule_extension = ".mdc"
+    command_extension = ".md"
+
+    mcp_global_path = ".cursor/mcp.json"
+    mcp_project_path = ".cursor/mcp.json"
+
+    def bundle_rules(
+        self, output_file: Path, section_globs: dict[str, str | None]
+    ) -> bool:
+        """Bundle Cursor rule files (.mdc) into a single output file."""
+        rules_dir = self.rules_dir
+        if not rules_dir:
+            return False
+
+        rules_path = output_file.parent / rules_dir
+
+        rule_ext = self.rule_extension
+        if not rule_ext:
+            return False
+
+        rule_files = list(rules_path.glob(f"*{rule_ext}"))
+
+        general = [f for f in rule_files if f.stem == "general"]
+        others = [f for f in rule_files if f.stem != "general"]
+
+        ordered_others = get_ordered_files(others, list(section_globs.keys()))
+        ordered = general + ordered_others
+
+        content_parts: list[str] = []
+        for rule_file in ordered:
+            content = rule_file.read_text().strip()
+            if not content:
+                continue
+
+            content = strip_yaml_frontmatter(content)
+            content = strip_header(content)
+            header = resolve_header_from_stem(rule_file.stem, section_globs)
+
+            if rule_file.stem != "general":
+                content_parts.append(f"## {header}\n\n")
+
+            content_parts.append(content)
+            content_parts.append("\n\n")
+
+        if not content_parts:
+            return False
+
+        output_file.write_text("".join(content_parts))
+        return True
+
+    def bundle_commands(
+        self, output_file: Path, section_globs: dict[str, str | None]
+    ) -> bool:
+        """Bundle Cursor command files (.md) into a single output file."""
+        commands_dir = self.commands_dir
+        if not commands_dir:
+            return False
+
+        commands_path = output_file.parent / commands_dir
+        if not commands_path.exists():
+            return False
+
+        command_ext = self.command_extension
+        if not command_ext:
+            return False
+
+        command_files = list(commands_path.glob(f"*{command_ext}"))
+        if not command_files:
+            return False
+
+        ordered_commands = get_ordered_files(command_files, list(section_globs.keys()))
+
+        content_parts: list[str] = []
+        for command_file in ordered_commands:
+            content = command_file.read_text().strip()
+            if not content:
+                continue
+
+            header = resolve_header_from_stem(command_file.stem, section_globs)
+            content_parts.append(f"## {header}\n\n")
+            content_parts.append(content)
+            content_parts.append("\n\n")
+
+        if not content_parts:
+            return False
+
+        output_file.write_text("".join(content_parts))
+        return True
+
+    def write_rule(
+        self,
+        content_lines: list[str],
+        filename: str,
+        rules_dir: Path,
+        glob_pattern: str | None = None,
+    ) -> None:
+        """Write a Cursor rule file (.mdc) with YAML frontmatter."""
+        extension = self.rule_extension or ".mdc"
+        filepath = rules_dir / f"{filename}{extension}"
+
+        if glob_pattern and glob_pattern != "manual":
+            header_yaml = f"""---
+description:
+globs: {glob_pattern}
+alwaysApply: false
+---
+"""
+        elif glob_pattern == "manual":
+            header_yaml = """---
+description:
+alwaysApply: false
+---
+"""
+        else:
+            header_yaml = """---
+description:
+alwaysApply: true
+---
+"""
+        write_rule_file(filepath, header_yaml, content_lines)
+
+    def write_command(
+        self,
+        content_lines: list[str],
+        filename: str,
+        commands_dir: Path,
+        section_name: str | None = None,
+    ) -> None:
+        """Write a Cursor command file (.md) - plain markdown, no frontmatter."""
+        extension = self.command_extension or ".md"
+        filepath = commands_dir / f"{filename}{extension}"
+
+        trimmed = trim_content(content_lines)
+        filepath.write_text("".join(trimmed))
+
+    def write_prompt(
+        self,
+        content_lines: list[str],
+        filename: str,
+        prompts_dir: Path,
+        section_name: str | None = None,
+    ) -> None:
+        """Write a Cursor prompt file (.mdc) with optional frontmatter."""
+        extension = self.rule_extension or ".mdc"
+        filepath = prompts_dir / f"{filename}{extension}"
+
+        description, filtered_content = extract_description_and_filter_content(
+            content_lines, ""
+        )
+
+        output_parts: list[str] = []
+        if description:
+            output_parts.append(f"---\ndescription: {description}\n---\n")
+
+        output_parts.extend(filtered_content)
+        filepath.write_text("".join(output_parts))