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

llm_ide_rules/commands/download.py

@@ -9,6 +9,8 @@ import requests
 import typer
 from typing_extensions import Annotated
 
+from llm_ide_rules.commands.explode import explode_implementation
+from llm_ide_rules.constants import VALID_AGENTS
 from llm_ide_rules.log import log
 
 DEFAULT_REPO = "iloveitaly/llm-ide-rules"
@@ -38,17 +40,39 @@ def normalize_repo(repo: str) -> str:
 
 
 # Define what files/directories each instruction type includes
+# For agents supported by 'explode' (cursor, github, gemini, claude, opencode),
+# we don't download specific directories anymore. Instead, we download the source
+# files (instructions.md, commands.md) and generate them locally using explode.
+# The directories listed here are what gets created by explode and what delete removes.
 INSTRUCTION_TYPES = {
-    "cursor": {"directories": [".cursor"], "files": []},
+    "cursor": {
+        "directories": [".cursor/rules", ".cursor/commands"],
+        "files": [],
+        "include_patterns": [],
+    },
     "github": {
-        "directories": [".github"],
+        "directories": [".github/instructions", ".github/prompts"],
+        "files": [".github/copilot-instructions.md"],
+        "include_patterns": [],
+    },
+    "gemini": {
+        "directories": [".gemini/commands"],
+        "files": [],
+        "generated_files": [],
+        "include_patterns": [],
+    },
+    "claude": {
+        "directories": [".claude/commands"],
         "files": [],
-        "exclude_patterns": ["workflows/*"],
+        "generated_files": ["CLAUDE.md"],
+        "include_patterns": [],
     },
-    "gemini": {"directories": [".gemini/commands"], "files": ["GEMINI.md"]},
-    "claude": {"directories": [".claude/commands"], "files": ["CLAUDE.md"]},
-    "agent": {"directories": [], "files": ["AGENT.md"]},
-    "agents": {"directories": [], "files": [], "recursive_files": ["AGENTS.md"]},
+    "opencode": {
+        "directories": [".opencode/commands"],
+        "files": [],
+        "include_patterns": [],
+    },
+    "agents": {"directories": [], "files": [], "generated_files": ["AGENTS.md"]},
 }
 
 # Default types to download when no specific types are specified
@@ -131,7 +155,10 @@ def copy_instruction_files(
 
                 # Copy all files from source to target
                 copy_directory_contents(
-                    source_dir, target_subdir, config.get("exclude_patterns", [])
+                    source_dir,
+                    target_subdir,
+                    config.get("exclude_patterns", []),
+                    config.get("include_patterns", []),
                 )
                 copied_items.append(f"{dir_name}/")
 
@@ -208,7 +235,10 @@ def copy_recursive_files(
 
 
 def copy_directory_contents(
-    source_dir: Path, target_dir: Path, exclude_patterns: list[str]
+    source_dir: Path,
+    target_dir: Path,
+    exclude_patterns: list[str],
+    include_patterns: list[str] = [],
 ):
     """Recursively copy directory contents, excluding specified patterns."""
     for item in source_dir.rglob("*"):
@@ -234,6 +264,22 @@ def copy_directory_contents(
                 log.debug("excluding file", file=relative_str, pattern=pattern)
                 continue
 
+            # Check if file matches any include pattern (if any provided)
+            if include_patterns:
+                matched_include = False
+                for include_pattern in include_patterns:
+                    # Match against filename only, or full relative path
+                    if item.match(include_pattern):
+                        matched_include = True
+                        break
+
+                if not matched_include:
+                    log.debug(
+                        "skipping file (not matched in include_patterns)",
+                        file=relative_str,
+                    )
+                    continue
+
             target_file = target_dir / relative_path
             target_file.parent.mkdir(parents=True, exist_ok=True)
             target_file.write_bytes(item.read_bytes())
@@ -243,7 +289,7 @@ def download_main(
     instruction_types: Annotated[
         list[str] | None,
         typer.Argument(
-            help="Types of instructions to download (cursor, github, gemini, claude, agent, agents). Downloads everything by default."
+            help="Types of instructions to download (cursor, github, gemini, claude, opencode, agents). Downloads everything by default."
         ),
     ] = None,
     repo: Annotated[
@@ -310,16 +356,79 @@ def download_main(
 
     try:
         # Copy instruction files
-        copied_items = copy_instruction_files(repo_dir, instruction_types, target_path)
+        copied_items = [
+            f"Downloaded: {item}"
+            for item in copy_instruction_files(repo_dir, instruction_types, target_path)
+        ]
+
+        # Check for source files (instructions.md, commands.md) and copy them if available
+        # These are needed for 'explode' logic
+        source_files = ["instructions.md", "commands.md"]
+        sources_copied = False
+
+        # Only copy source files if we have at least one agent that uses explode
+        has_explode_agent = any(t in VALID_AGENTS for t in instruction_types)
+
+        if has_explode_agent:
+            for source_file in source_files:
+                src = repo_dir / source_file
+                dst = target_path / source_file
+                if src.exists():
+                    log.info("copying source file", source=str(src), target=str(dst))
+                    dst.parent.mkdir(parents=True, exist_ok=True)
+                    dst.write_bytes(src.read_bytes())
+                    copied_items.append(f"Downloaded: {source_file}")
+                    sources_copied = True
+
+        # Generate rule files locally for supported agents
+        explodable_agents = [t for t in instruction_types if t in VALID_AGENTS]
+
+        if explodable_agents:
+            if not sources_copied:
+                # Check if they existed in target already?
+                if not (target_path / "instructions.md").exists():
+                    log.warning(
+                        "source file instructions.md missing, generation might fail"
+                    )
+
+            for agent in explodable_agents:
+                log.info("generating rules locally", agent=agent)
+                try:
+                    explode_implementation(
+                        input_file="instructions.md",
+                        agent=agent,
+                        working_dir=target_path,
+                    )
+                    copied_items.append(f"Generated: {agent} rules")
+                except Exception as e:
+                    log.error("failed to generate rules", agent=agent, error=str(e))
+                    typer.echo(
+                        f"Warning: Failed to generate rules for {agent}: {e}", err=True
+                    )
 
         if copied_items:
-            success_msg = f"Downloaded {len(copied_items)} items to {target_path}:"
+            success_msg = f"Downloaded/Generated items in {target_path}:"
             typer.echo(typer.style(success_msg, fg=typer.colors.GREEN))
             for item in copied_items:
                 typer.echo(f"  - {item}")
         else:
-            log.warning("no files were copied")
-            typer.echo("No matching instruction files found in the repository.")
+            log.info("no files were copied or generated")
+
+            # Build list of expected files
+            expected_files = []
+            for inst_type in instruction_types:
+                config = INSTRUCTION_TYPES[inst_type]
+                expected_files.extend(config.get("directories", []))
+                expected_files.extend(config.get("files", []))
+                expected_files.extend(config.get("recursive_files", []))
+
+            error_msg = "No matching instruction files found in the repository."
+            typer.echo(typer.style(error_msg, fg=typer.colors.RED), err=True)
+
+            if expected_files:
+                typer.echo("\nExpected files/directories:", err=True)
+                for expected in expected_files:
+                    typer.echo(f"  - {expected}", err=True)
 
     finally:
         # Clean up temporary directory

llm_ide_rules/commands/explode.py

@@ -12,59 +12,8 @@ from llm_ide_rules.agents.base import (
     write_rule_file,
 )
 from llm_ide_rules.log import log
-from llm_ide_rules.constants import load_section_globs, header_to_filename, VALID_AGENTS
-
-
-def extract_general(lines: list[str]) -> list[str]:
-    """Extract lines before the first section header '## '."""
-    general = []
-    for line in lines:
-        if line.startswith("## "):
-            break
-        general.append(line)
-
-    return general
-
-
-def extract_section(lines: list[str], header: str) -> list[str]:
-    """Extract lines under a given section header until the next header or EOF.
-
-    Includes the header itself in the output.
-    """
-    content = []
-    in_section = False
-    for line in lines:
-        if in_section:
-            if line.startswith("## "):
-                break
-            content.append(line)
-        elif line.strip().lower() == header.lower():
-            in_section = True
-            content.append(line)
-
-    return content
-
-
-def extract_all_sections(lines: list[str]) -> dict[str, list[str]]:
-    """Extract all sections from lines, returning dict of section_name -> content_lines."""
-    sections: dict[str, list[str]] = {}
-    current_section: str | None = None
-    current_content: list[str] = []
-
-    for line in lines:
-        if line.startswith("## "):
-            if current_section:
-                sections[current_section] = current_content
-
-            current_section = line.strip()[3:]
-            current_content = [line]
-        elif current_section:
-            current_content.append(line)
-
-    if current_section:
-        sections[current_section] = current_content
-
-    return sections
+from llm_ide_rules.constants import header_to_filename, VALID_AGENTS
+from llm_ide_rules.markdown_parser import parse_sections
 
 
 def process_command_section(
@@ -105,31 +54,31 @@ def process_unmapped_as_always_apply(
     section_content = replace_header_with_proper_casing(section_content, section_name)
 
     cursor_agent.write_rule(
-        section_content, filename, cursor_rules_dir, glob_pattern=None
+        section_content,
+        filename,
+        cursor_rules_dir,
+        glob_pattern=None,
+        description=section_name,
+    )
+    github_agent.write_rule(
+        section_content,
+        filename,
+        copilot_dir,
+        glob_pattern=None,
+        description=section_name,
     )
-    github_agent.write_rule(section_content, filename, copilot_dir, glob_pattern=None)
 
     return True
 
 
-def explode_main(
-    input_file: Annotated[
-        str, typer.Argument(help="Input markdown file")
-    ] = "instructions.md",
-    config: Annotated[
-        str | None,
-        typer.Option("--config", "-c", help="Custom configuration file path"),
-    ] = None,
-    agent: Annotated[
-        str,
-        typer.Option(
-            "--agent",
-            "-a",
-            help="Agent to explode for (cursor, github, claude, gemini, or all)",
-        ),
-    ] = "all",
+def explode_implementation(
+    input_file: str = "instructions.md",
+    agent: str = "all",
+    working_dir: Path | None = None,
 ) -> None:
-    """Convert instruction file to separate rule files."""
+    """Core implementation of explode command."""
+    if working_dir is None:
+        working_dir = Path.cwd()
 
     if agent not in VALID_AGENTS:
         log.error("invalid agent", agent=agent, valid_agents=VALID_AGENTS)
@@ -139,18 +88,24 @@ def explode_main(
         typer.echo(typer.style(error_msg, fg=typer.colors.RED), err=True)
         raise typer.Exit(1)
 
-    section_globs = load_section_globs(config)
-
     log.info(
-        "starting explode operation", input_file=input_file, agent=agent, config=config
+        "starting explode operation",
+        input_file=input_file,
+        agent=agent,
+        working_dir=str(working_dir),
     )
 
-    cwd = Path.cwd()
-
     # Initialize only the agents we need
     agents_to_process = []
     if agent == "all":
-        agents_to_process = ["cursor", "github", "claude", "gemini", "opencode"]
+        agents_to_process = [
+            "cursor",
+            "github",
+            "claude",
+            "gemini",
+            "opencode",
+            "agents",
+        ]
     else:
         agents_to_process = [agent]
 
@@ -163,21 +118,21 @@ def explode_main(
 
         if agent_name in ["cursor", "github"]:
             # These agents have both rules and commands
-            rules_dir = cwd / agent_instances[agent_name].rules_dir
-            commands_dir = cwd / agent_instances[agent_name].commands_dir
-            rules_dir.mkdir(parents=True, exist_ok=True)
-            commands_dir.mkdir(parents=True, exist_ok=True)
+            rules_dir = working_dir / agent_instances[agent_name].rules_dir
+            commands_dir = working_dir / agent_instances[agent_name].commands_dir
             agent_dirs[agent_name] = {"rules": rules_dir, "commands": commands_dir}
-        else:
+        elif agent_instances[agent_name].commands_dir:
             # claude, gemini, and opencode only have commands
-            commands_dir = cwd / agent_instances[agent_name].commands_dir
-            commands_dir.mkdir(parents=True, exist_ok=True)
+            commands_dir = working_dir / agent_instances[agent_name].commands_dir
             agent_dirs[agent_name] = {"commands": commands_dir}
+        else:
+            # agents has neither rules nor commands dirs (only generates root doc)
+            agent_dirs[agent_name] = {}
 
-    input_path = cwd / input_file
+    input_path = working_dir / input_file
 
     try:
-        lines = input_path.read_text().splitlines(keepends=True)
+        input_text = input_path.read_text()
     except FileNotFoundError:
         log.error("input file not found", input_file=str(input_path))
         error_msg = f"Input file not found: {input_path}"
@@ -185,17 +140,20 @@ def explode_main(
         raise typer.Exit(1)
 
     commands_path = input_path.parent / "commands.md"
-    commands_lines = []
+    commands_text = ""
     if commands_path.exists():
-        commands_lines = commands_path.read_text().splitlines(keepends=True)
+        commands_text = commands_path.read_text()
         log.info("found commands file", commands_file=str(commands_path))
 
+    # Parse instructions
+    general, instruction_sections = parse_sections(input_text)
+
     # Process general instructions for agents that support rules
-    general = extract_general(lines)
     if any(line.strip() for line in general):
         general_header = """
 ---
-description:
+description: General Instructions
+globs: 
 alwaysApply: true
 ---
 """
@@ -204,26 +162,61 @@ alwaysApply: true
                 agent_dirs["cursor"]["rules"] / "general.mdc", general_header, general
             )
         if "github" in agent_instances:
-            agent_instances["github"].write_general_instructions(general, cwd)
-
-    # Process mapped sections for agents that support rules
-    found_sections = set()
-    for section_name, glob_pattern in section_globs.items():
-        section_content = extract_section(lines, f"## {section_name}")
-        if any(line.strip() for line in section_content):
-            found_sections.add(section_name)
-            filename = header_to_filename(section_name)
-
-            section_content = replace_header_with_proper_casing(
-                section_content, section_name
-            )
+            agent_instances["github"].write_general_instructions(general, working_dir)
+
+    # Process sections for agents that support rules
+    rules_sections: dict[str, list[str]] = {}
+    section_globs: dict[str, str | None] = {}
+
+    for section_name, section_data in instruction_sections.items():
+        content = section_data.content
+        glob_pattern = section_data.glob_pattern
 
+        if not any(line.strip() for line in content):
+            continue
+
+        rules_sections[section_name] = content
+        section_globs[section_name] = glob_pattern
+        filename = header_to_filename(section_name)
+
+        section_content = replace_header_with_proper_casing(content, section_name)
+
+        if glob_pattern is None:
+            # No directive = alwaysApply
+            if "cursor" in agent_instances and "github" in agent_instances:
+                process_unmapped_as_always_apply(
+                    section_name,
+                    section_content,
+                    agent_instances["cursor"],
+                    agent_instances["github"],
+                    agent_dirs["cursor"]["rules"],
+                    agent_dirs["github"]["rules"],
+                )
+            elif "cursor" in agent_instances:
+                agent_instances["cursor"].write_rule(
+                    section_content,
+                    filename,
+                    agent_dirs["cursor"]["rules"],
+                    glob_pattern=None,
+                    description=section_name,
+                )
+            elif "github" in agent_instances:
+                agent_instances["github"].write_rule(
+                    section_content,
+                    filename,
+                    agent_dirs["github"]["rules"],
+                    glob_pattern=None,
+                    description=section_name,
+                )
+        elif glob_pattern != "manual":
+            # Has glob pattern = file-specific rule
             if "cursor" in agent_instances:
                 agent_instances["cursor"].write_rule(
                     section_content,
                     filename,
                     agent_dirs["cursor"]["rules"],
                     glob_pattern,
+                    description=section_name,
                 )
             if "github" in agent_instances:
                 agent_instances["github"].write_rule(
@@ -231,73 +224,40 @@ alwaysApply: true
                     filename,
                     agent_dirs["github"]["rules"],
                     glob_pattern,
+                    description=section_name,
                 )
 
-    for section_name in section_globs:
-        if section_name not in found_sections:
-            log.warning("section not found in file", section=section_name)
-
-    # Process unmapped sections for agents that support rules
-    if "cursor" in agent_instances or "github" in agent_instances:
-        for line in lines:
-            if line.startswith("## "):
-                section_name = line.strip()[3:]
-                if not any(
-                    section_name.lower() == mapped_section.lower()
-                    for mapped_section in section_globs
-                ):
-                    log.warning(
-                        "unmapped section in instructions.md, treating as always-apply rule",
-                        section=section_name,
-                    )
-                    section_content = extract_section(lines, f"## {section_name}")
-
-                    if "cursor" in agent_instances and "github" in agent_instances:
-                        process_unmapped_as_always_apply(
-                            section_name,
-                            section_content,
-                            agent_instances["cursor"],
-                            agent_instances["github"],
-                            agent_dirs["cursor"]["rules"],
-                            agent_dirs["github"]["rules"],
-                        )
-                    elif "cursor" in agent_instances:
-                        # Only cursor - write just cursor rules
-                        if any(line.strip() for line in section_content):
-                            filename = header_to_filename(section_name)
-                            section_content = replace_header_with_proper_casing(
-                                section_content, section_name
-                            )
-                            agent_instances["cursor"].write_rule(
-                                section_content,
-                                filename,
-                                agent_dirs["cursor"]["rules"],
-                                glob_pattern=None,
-                            )
-                    elif "github" in agent_instances:
-                        # Only github - write just github rules
-                        if any(line.strip() for line in section_content):
-                            filename = header_to_filename(section_name)
-                            section_content = replace_header_with_proper_casing(
-                                section_content, section_name
-                            )
-                            agent_instances["github"].write_rule(
-                                section_content,
-                                filename,
-                                agent_dirs["github"]["rules"],
-                                glob_pattern=None,
-                            )
-
     # Process commands for all agents
-    if commands_lines:
-        command_sections = extract_all_sections(commands_lines)
-        agents = [agent_instances[name] for name in agents_to_process]
+    command_sections_data = {}
+    command_sections = {}
+    if commands_text:
+        _, command_sections_data = parse_sections(commands_text)
+        agents_with_commands = [
+            agent_instances[name]
+            for name in agents_to_process
+            if agent_instances[name].commands_dir
+        ]
         command_dirs = {
-            name: agent_dirs[name]["commands"] for name in agents_to_process
+            name: agent_dirs[name]["commands"]
+            for name in agents_to_process
+            if "commands" in agent_dirs[name]
         }
 
-        for section_name, section_content in command_sections.items():
-            process_command_section(section_name, section_content, agents, command_dirs)
+        for section_name, section_data in command_sections_data.items():
+            command_sections[section_name] = section_data.content
+            process_command_section(
+                section_name, section_data.content, agents_with_commands, command_dirs
+            )
+
+    # Generate root documentation (CLAUDE.md, GEMINI.md, etc.)
+    for agent_name, agent_inst in agent_instances.items():
+        agent_inst.generate_root_doc(
+            general,
+            rules_sections,
+            command_sections,
+            working_dir,
+            section_globs=section_globs,
+        )
 
     # Build log message and user output based on processed agents
     log_data = {"agent": agent}
@@ -308,13 +268,52 @@ alwaysApply: true
             log_data[f"{agent_name}_rules"] = str(agent_dirs[agent_name]["rules"])
             log_data[f"{agent_name}_commands"] = str(agent_dirs[agent_name]["commands"])
             created_dirs.append(f".{agent_name}/")
-        else:
+        elif agent_dirs[agent_name]:
+            # Has commands directory
             log_data[f"{agent_name}_commands"] = str(agent_dirs[agent_name]["commands"])
             created_dirs.append(f".{agent_name}/")
+        # else: agent has no directories (e.g., agents which only generates root doc)
 
-    if len(created_dirs) == 1:
-        success_msg = f"Created files in {created_dirs[0]} directory"
-        typer.echo(typer.style(success_msg, fg=typer.colors.GREEN))
+    if "gemini" in agent_instances:
+        if not agent_instances["gemini"].check_agents_md_config(working_dir):
+            typer.secho(
+                "Warning: Gemini CLI configuration missing for AGENTS.md.",
+                fg=typer.colors.YELLOW,
+            )
+            typer.secho(
+                "Run this command to configure it:",
+                fg=typer.colors.YELLOW,
+            )
+            typer.secho(
+                "  gemini config set agent.instructionFile AGENTS.md",
+                fg=typer.colors.YELLOW,
+            )
+
+    if created_dirs:
+        if len(created_dirs) == 1:
+            success_msg = f"Created files in {created_dirs[0]} directory"
+            typer.echo(typer.style(success_msg, fg=typer.colors.GREEN))
+        else:
+            success_msg = f"Created files in {', '.join(created_dirs)} directories"
+            typer.echo(typer.style(success_msg, fg=typer.colors.GREEN))
     else:
-        success_msg = f"Created files in {', '.join(created_dirs)} directories"
+        # No directories created (e.g., agents that only generate root docs)
+        success_msg = "Created root documentation files"
         typer.echo(typer.style(success_msg, fg=typer.colors.GREEN))
+
+
+def explode_main(
+    input_file: Annotated[
+        str, typer.Argument(help="Input markdown file")
+    ] = "instructions.md",
+    agent: Annotated[
+        str,
+        typer.Option(
+            "--agent",
+            "-a",
+            help="Agent to explode for (cursor, github, claude, gemini, or all)",
+        ),
+    ] = "all",
+) -> None:
+    """Convert instruction file to separate rule files."""
+    explode_implementation(input_file, agent, Path.cwd())