patchllm 0.2.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

patchllm/main.py

@@ -1,286 +1,4 @@
-import textwrap
-import argparse
-import litellm
-import pprint
-import os
-from dotenv import load_dotenv
-from rich.console import Console
-from rich.panel import Panel
-
-from .context import build_context
-from .parser import paste_response
-from .utils import load_from_py_file
-
-console = Console()
-
-# --- Core Functions ---
-
-def collect_context(config_name, configs):
-    """Builds the code context from a provided configuration dictionary."""
-    console.print("\n--- Building Code Context... ---", style="bold")
-    if not configs:
-        raise FileNotFoundError("Could not find a 'configs.py' file.")
-    selected_config = configs.get(config_name)
-    if selected_config is None:
-        raise KeyError(f"Context config '{config_name}' not found in provided configs file.")
-    
-    context_object = build_context(selected_config)
-    if context_object:
-        tree, context = context_object.values()
-        console.print("--- Context Building Finished. The following files were extracted ---", style="bold")
-        console.print(tree)
-        return context
-    else:
-        console.print("--- Context Building Failed (No files found) ---", style="yellow")
-        return None
-
-def run_update(task_instructions, model_name, history, context=None):
-    """
-    Assembles the final prompt, sends it to the LLM, and applies file updates.
-    """
-    console.print("\n--- Sending Prompt to LLM... ---", style="bold")
-    final_prompt = task_instructions
-    if context:
-        final_prompt = f"{context}\n\n{task_instructions}"
-    
-    history.append({"role": "user", "content": final_prompt})
-    
-    try:
-        with console.status("[bold cyan]Waiting for LLM response...", spinner="dots"):
-            response = litellm.completion(model=model_name, messages=history)
-        
-        assistant_response_content = response.choices[0].message.content
-        history.append({"role": "assistant", "content": assistant_response_content})
-
-        if not assistant_response_content or not assistant_response_content.strip():
-            console.print("⚠️  Response is empty. Nothing to paste.", style="yellow")
-            return
-        
-        console.print("\n--- Updating files ---", style="bold")
-        paste_response(assistant_response_content)
-        console.print("--- File Update Process Finished ---", style="bold")
-
-    except Exception as e:
-        history.pop() # Keep history clean on error
-        raise RuntimeError(f"An error occurred while communicating with the LLM via litellm: {e}") from e
-
-def write_context_to_file(file_path, context):
-    """Utility function to write the context to a file."""
-    console.print("Exporting context..", style="cyan")
-    with open(file_path, "w", encoding="utf-8") as file:
-        file.write(context)
-    console.print(f'✅ Context exported to {file_path.split("/")[-1]}', style="green")
-
-def read_from_file(file_path):
-    """Utility function to read and return the content of a file."""
-    console.print(f"Importing from {file_path}..", style="cyan")
-    try:
-        with open(file_path, "r", encoding="utf-8") as file:
-            content = file.read()
-            console.print("✅ Finished reading file.", style="green")
-            return content
-    except Exception as e:
-        raise RuntimeError(f"Failed to read from file {file_path}: {e}") from e
-
-def create_new_config(configs, configs_file_str):
-    """Interactively creates a new configuration and saves it to the specified configs file."""
-    console.print(f"\n--- Creating a new configuration in '{configs_file_str}' ---", style="bold")
-    
-    try:
-        name = console.input("[bold]Enter a name for the new configuration: [/]").strip()
-        if not name:
-            console.print("❌ Configuration name cannot be empty.", style="red")
-            return
-
-        if name in configs:
-            overwrite = console.input(f"Configuration '[bold]{name}[/]' already exists. Overwrite? (y/n): ").lower()
-            if overwrite not in ['y', 'yes']:
-                console.print("Operation cancelled.", style="yellow")
-                return
-
-        path = console.input("[bold]Enter the base path[/] (e.g., '.' for current directory): ").strip() or "."
-        
-        console.print("\nEnter comma-separated glob patterns for files to include.")
-        include_raw = console.input('[cyan]> (e.g., "[bold]**/*.py, src/**/*.js[/]"): [/]').strip()
-        include_patterns = [p.strip() for p in include_raw.split(',') if p.strip()]
-
-        console.print("\nEnter comma-separated glob patterns for files to exclude (optional).")
-        exclude_raw = console.input('[cyan]> (e.g., "[bold]**/tests/*, venv/*[/]"): [/]').strip()
-        exclude_patterns = [p.strip() for p in exclude_raw.split(',') if p.strip()]
-        
-        console.print("\nEnter comma-separated URLs to include as context (optional).")
-        urls_raw = console.input('[cyan]> (e.g., "[bold]https://docs.example.com, ...[/]"): [/]').strip()
-        urls = [u.strip() for u in urls_raw.split(',') if u.strip()]
-
-        new_config_data = {
-            "path": path,
-            "include_patterns": include_patterns,
-            "exclude_patterns": exclude_patterns,
-            "urls": urls,
-        }
-
-        configs[name] = new_config_data
-
-        with open(configs_file_str, "w", encoding="utf-8") as f:
-            f.write("# configs.py\n")
-            f.write("configs = ")
-            f.write(pprint.pformat(configs, indent=4))
-            f.write("\n")
-        
-        console.print(f"\n✅ Successfully created and saved configuration '[bold]{name}[/]' in '[bold]{configs_file_str}[/]'.", style="green")
-
-    except KeyboardInterrupt:
-        console.print("\n\n⚠️ Configuration creation cancelled by user.", style="yellow")
-        return
-
-def main():
-    """
-    Main entry point for the patchllm command-line tool.
-    """
-    load_dotenv()
-    
-    configs_file_path = os.getenv("PATCHLLM_CONFIGS_FILE", "./configs.py")
-
-    parser = argparse.ArgumentParser(
-        description="A CLI tool to apply code changes using an LLM.",
-        formatter_class=argparse.RawTextHelpFormatter
-    )
-
-    parser.add_argument("-i", "--init", action="store_true", help="Create a new configuration interactively.")
-    
-    parser.add_argument("-c", "--config", type=str, default=None, help="Name of the config key to use from the configs file.")
-    parser.add_argument("-t", "--task", type=str, default=None, help="The task instructions to guide the assistant.")
-    
-    parser.add_argument("-co", "--context-out", nargs='?', const="context.md", default=None, help="Export the generated context to a file. Defaults to 'context.md'.")
-    parser.add_argument("-ci", "--context-in", type=str, default=None, help="Import a previously saved context from a file.")
-    
-    parser.add_argument("-u", "--update", type=str, default="True", help="Control whether to send the context to the LLM for updates. (True/False)")
-    parser.add_argument("-ff", "--from-file", type=str, default=None, help="Apply updates directly from a file instead of the LLM.")
-    parser.add_argument("-fc", "--from-clipboard", action="store_true", help="Apply updates directly from the clipboard.")
-    
-    parser.add_argument("--model", type=str, default="gemini/gemini-1.5-flash", help="Model name to use (e.g., 'gpt-4o', 'claude-3-sonnet').")
-    parser.add_argument("--voice", type=str, default="False", help="Enable voice interaction for providing task instructions. (True/False)")
-    
-    parser.add_argument("--list-configs", action="store_true", help="List all available configurations from the configs file and exit.")
-    parser.add_argument("--show-config", type=str, help="Display the settings for a specific configuration and exit.")
-    
-    args = parser.parse_args()
-
-    try:
-        configs = load_from_py_file(configs_file_path, "configs")
-    except FileNotFoundError:
-        configs = {}
-        if not any([args.init, args.list_configs, args.show_config]):
-             console.print(f"⚠️  Config file '{configs_file_path}' not found. You can create one with the --init flag.", style="yellow")
-
-
-    if args.list_configs:
-        console.print(f"Available configurations in '[bold]{configs_file_path}[/]':", style="bold")
-        if not configs:
-            console.print(f"  -> No configurations found or '{configs_file_path}' is missing.")
-        else:
-            for config_name in configs:
-                console.print(f"  - {config_name}")
-        return
-
-    if args.show_config:
-        config_name = args.show_config
-        if not configs:
-            console.print(f"⚠️  Config file '{configs_file_path}' not found or is empty.", style="yellow")
-            return
-        
-        config_data = configs.get(config_name)
-        if config_data:
-            pretty_config = pprint.pformat(config_data, indent=2)
-            console.print(
-                Panel(
-                    pretty_config,
-                    title=f"[bold cyan]Configuration: '{config_name}'[/]",
-                    subtitle=f"[dim]from {configs_file_path}[/dim]",
-                    border_style="blue"
-                )
-            )
-        else:
-            console.print(f"❌ Configuration '[bold]{config_name}[/]' not found in '{configs_file_path}'.", style="red")
-        return
-
-    if args.init:
-        create_new_config(configs, configs_file_path)
-        return
-
-    if args.from_clipboard:
-        try:
-            import pyperclip
-            updates = pyperclip.paste()
-            if updates:
-                console.print("--- Parsing updates from clipboard ---", style="bold")
-                paste_response(updates)
-            else:
-                console.print("⚠️ Clipboard is empty. Nothing to parse.", style="yellow")
-        except ImportError:
-            console.print("❌ The 'pyperclip' library is required for clipboard functionality.", style="red")
-            console.print("Please install it using: pip install pyperclip", style="cyan")
-        except Exception as e:
-            console.print(f"❌ An error occurred while reading from the clipboard: {e}", style="red")
-        return
-
-    if args.from_file:
-        updates = read_from_file(args.from_file)
-        paste_response(updates)
-        return
-        
-    system_prompt = textwrap.dedent("""
-        You are an expert pair programmer. Your purpose is to help users by modifying files based on their instructions.
-        Follow these rules strictly:
-        Your output should be a single file including all the updated files. For each file-block:
-        1. Only include code for files that need to be updated / edited.
-        2. For updated files, do not exclude any code even if it is unchanged code; assume the file code will be copy-pasted full in the file.
-        3. Do not include verbose inline comments explaining what every small change does. Try to keep comments concise but informative, if any.
-        4. Only update the relevant parts of each file relative to the provided task; do not make irrelevant edits even if you notice areas of improvements elsewhere.
-        5. Do not use diffs.
-        6. Make sure each file-block is returned in the following exact format. No additional text, comments, or explanations should be outside these blocks.
-        Expected format for a modified or new file:
-        <file_path:/absolute/path/to/your/file.py>
-        ```python
-        # The full, complete content of /absolute/path/to/your/file.py goes here.
-        def example_function():
-            return "Hello, World!"
-        ```
-    """)
-    history = [{"role": "system", "content": system_prompt}]
-    
-    context = None
-    if args.voice not in ["False", "false"]:
-        from .listener import listen, speak
-        speak("Say your task instruction.")
-        task = listen()
-        if not task:
-            speak("No instruction heard. Exiting.")
-            return
-        speak(f"You said: {task}. Should I proceed?")
-        confirm = listen()
-        if confirm and "yes" in confirm.lower():
-            context = collect_context(args.config, configs)
-            run_update(task, args.model, history, context)
-            speak("Changes applied.")
-        else:
-            speak("Cancelled.")
-        return
-
-    if args.context_in:
-        context = read_from_file(args.context_in)
-    else:
-        if not args.config:
-            parser.error("A --config name is required unless using other flags like --context-in or other utility flags.")
-        context = collect_context(args.config, configs)
-        if context and args.context_out:
-            write_context_to_file(args.context_out, context)
-
-    if args.update not in ["False", "false"]:
-        if not args.task:
-            parser.error("The --task argument is required to generate updates.")
-        if context:
-            run_update(args.task, args.model, history, context)
+from .cli.entrypoint import main
 
 if __name__ == "__main__":
     main()

patchllm/parser.py

@@ -1,3 +1,4 @@
+import difflib
 import re
 from pathlib import Path
 from rich.console import Console
@@ -6,80 +7,135 @@ from rich.text import Text
 
 console = Console()
 
-def paste_response(response_content):
+def _parse_file_blocks(response: str) -> list[tuple[Path, str]]:
+    """Parses the LLM response to extract file paths and their content."""
+    pattern = r"<file_path:(.*?)>\n```(?:\w+\n)?(.*?)\n```"
+    matches = re.findall(pattern, response, re.DOTALL)
+    
+    parsed_blocks = []
+    for path_str, content in matches:
+        path_obj = Path(path_str.strip()).resolve()
+        # --- CORRECTION: Strip leading/trailing whitespace from content ---
+        parsed_blocks.append((path_obj, content.strip()))
+        
+    return parsed_blocks
+
+def parse_change_summary(response: str) -> str | None:
+    """Parses the LLM response to extract the change summary."""
+    pattern = r"<change_summary>(.*?)</change_summary>"
+    match = re.search(pattern, response, re.DOTALL)
+    if match:
+        return match.group(1).strip()
+    return None
+
+def paste_response(response: str):
+    """Applies all file updates from the LLM's response to the local filesystem."""
+    parsed_blocks = _parse_file_blocks(response)
+    if not parsed_blocks:
+        console.print("⚠️  Could not find any file blocks to apply in the response.", style="yellow")
+        return
+        
+    for file_path, new_content in parsed_blocks:
+        try:
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text(new_content, encoding="utf-8")
+            console.print(f"✅ Updated [bold cyan]{file_path.name}[/bold cyan]", style="green")
+        except Exception as e:
+            console.print(f"❌ Failed to write to {file_path}: {e}", style="red")
+
+def paste_response_selectively(response: str, files_to_apply: list[str]):
     """
-    Parses a response containing code blocks and writes them to files,
-    handling both absolute and relative paths safely.
+    Applies file updates from the LLM's response only to the user-selected files.
 
     Args:
-        response_content (str): The string response from the LLM.
+        response (str): The full response from the LLM.
+        files_to_apply (list[str]): A list of absolute file path strings to modify.
     """
-    pattern = re.compile(
-        r"<file_path:([^>]+?)>\s*```(?:.*?)\n(.*?)\n```",
-        re.DOTALL | re.MULTILINE
-    )
+    parsed_blocks = _parse_file_blocks(response)
+    if not parsed_blocks:
+        console.print("⚠️  Could not find any file blocks to apply in the response.", style="yellow")
+        return
 
-    matches = pattern.finditer(response_content)
-    
-    files_written = []
-    files_skipped = []
-    files_failed = []
-    found_matches = False
-
-    for match in matches:
-        found_matches = True
-        file_path_str = match.group(1).strip()
-        code_content = match.group(2)
-
-        if not file_path_str:
-            console.print("⚠️ Found a code block with an empty file path. Skipping.", style="yellow")
-            continue
-
-        console.print(f"Found path in response: '[cyan]{file_path_str}[/]'")
-        raw_path = Path(file_path_str)
-        
-        if raw_path.is_absolute():
-            target_path = raw_path
+    files_to_apply_set = set(files_to_apply)
+    applied_count = 0
+
+    for file_path, new_content in parsed_blocks:
+        if file_path.as_posix() in files_to_apply_set:
+            try:
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+                file_path.write_text(new_content, encoding="utf-8")
+                console.print(f"✅ Updated [bold cyan]{file_path.name}[/bold cyan]", style="green")
+                applied_count += 1
+            except Exception as e:
+                console.print(f"❌ Failed to write to {file_path}: {e}", style="red")
+
+    if applied_count == 0:
+        console.print("No changes were applied.", style="yellow")
+
+
+def summarize_changes(response: str) -> dict:
+    """Summarizes which files will be created and which will be modified."""
+    parsed_blocks = _parse_file_blocks(response)
+    summary = {"created": [], "modified": []}
+    for file_path, _ in parsed_blocks:
+        if file_path.exists():
+            summary["modified"].append(file_path.as_posix())
         else:
-            target_path = Path.cwd() / raw_path
+            summary["created"].append(file_path.as_posix())
+    return summary
 
-        target_path = target_path.resolve()
+def get_diff_for_file(file_path_str: str, response: str) -> str:
+    """Generates a colorized, unified diff for a single file from the response."""
+    parsed_blocks = _parse_file_blocks(response)
+    file_path = Path(file_path_str).resolve()
+    
+    new_content = None
+    for p, content in parsed_blocks:
+        if p == file_path:
+            new_content = content
+            break
+            
+    if new_content is None:
+        return f"Could not find content for {file_path_str} in the response."
 
+    original_content = ""
+    if file_path.exists():
         try:
-            target_path.parent.mkdir(parents=True, exist_ok=True)
-
-            if target_path.exists():
-                with open(target_path, 'r', encoding='utf-8') as existing_file:
-                    if existing_file.read() == code_content:
-                        console.print(f"  -> No changes for '[cyan]{target_path}[/]', skipping.", style="dim")
-                        files_skipped.append(target_path)
-                        continue
+            original_content = file_path.read_text(encoding="utf-8")
+        except Exception:
+            return f"Could not read original content of {file_path_str}."
 
-            with open(target_path, 'w', encoding='utf-8') as outfile:
-                outfile.write(code_content)
+    diff = difflib.unified_diff(
+        original_content.splitlines(keepends=True),
+        new_content.splitlines(keepends=True),
+        fromfile=f"a/{file_path.name}",
+        tofile=f"b/{file_path.name}",
+    )
 
-            console.print(f"  -> ✅ Wrote {len(code_content)} bytes to '[cyan]{target_path}[/]'", style="green")
-            files_written.append(target_path)
+    diff_text = Text()
+    for line in diff:
+        if line.startswith('+'):
+            diff_text.append(line, style="green")
+        elif line.startswith('-'):
+            diff_text.append(line, style="red")
+        elif line.startswith('^'):
+            diff_text.append(line, style="blue")
+        else:
+            diff_text.append(line)
+            
+    return diff_text
 
-        except OSError as e:
-            console.print(f"  -> ❌ Error writing file '[cyan]{target_path}[/]': {e}", style="red")
-            files_failed.append(target_path)
-        except Exception as e:
-            console.print(f"  -> ❌ An unexpected error occurred for file '[cyan]{target_path}[/]': {e}", style="red")
-            files_failed.append(target_path)
-
-    summary_text = Text()
-    if not found_matches:
-        summary_text.append("No file paths and code blocks matching the expected format were found in the response.", style="yellow")
-    else:
-        if files_written:
-            summary_text.append(f"Successfully wrote {len(files_written)} file(s).\n", style="green")
-        if files_skipped:
-            summary_text.append(f"Skipped {len(files_skipped)} file(s) (no changes).\n", style="cyan")
-        if files_failed:
-            summary_text.append(f"Failed to write {len(files_failed)} file(s).\n", style="red")
+def display_diff(response: str):
+    """Displays the diff for all changes proposed in the response."""
+    summary = summarize_changes(response)
+    all_files = summary.get("modified", []) + summary.get("created", [])
+    
+    console.print("\n--- Proposed Changes (Diff) ---", style="bold yellow")
+    
+    if not all_files:
+        console.print("No file changes detected in the response.")
+        return
         
-        if not any([files_written, files_skipped, files_failed]):
-             summary_text.append("Found matching blocks, but no files were processed.", style="yellow")
-
-    console.print(Panel(summary_text, title="[bold]Summary[/bold]", border_style="blue"))
+    for file_path in all_files:
+        diff_text = get_diff_for_file(file_path, response)
+        console.print(Panel(diff_text, title=f"[bold cyan]Diff: {Path(file_path).name}[/bold cyan]", border_style="yellow"))

patchllm/patcher.py

@@ -0,0 +1,118 @@
+import subprocess
+import re
+from pathlib import Path
+from rich.console import Console
+from InquirerPy import prompt
+from InquirerPy.exceptions import InvalidArgument
+import textwrap
+
+from .parser import get_diff_for_file, _parse_file_blocks, paste_response
+from .scopes.helpers import find_files
+
+console = Console()
+
+def _is_diff_format(text: str) -> bool:
+    """Checks if the text appears to be in the unified diff format."""
+    for line in text.splitlines():
+        if line.strip(): # Find the first non-empty line
+            return line.startswith("--- a/")
+    return False
+
+def _apply_diff(diff_text: str, base_path: Path):
+    """Applies a patch using the system's `patch` command."""
+    try:
+        # --- MODIFICATION: Added --ignore-whitespace for robustness ---
+        proc = subprocess.run(
+            ["patch", "-p1", "--ignore-whitespace"],
+            input=diff_text,
+            text=True,
+            capture_output=True,
+            check=True,
+            cwd=base_path
+        )
+        console.print("✅ Patch applied successfully.", style="green")
+        if proc.stdout:
+            console.print(proc.stdout)
+    except FileNotFoundError:
+        console.print("❌ Failed to apply patch.", style="red")
+        console.print("Error: The 'patch' command-line utility was not found.", style="yellow")
+        console.print("Please install it to apply diff-formatted patches:", style="yellow")
+        console.print("  - On Debian/Ubuntu: sudo apt-get install patch", style="cyan")
+        console.print("  - On macOS (Homebrew): brew install patch", style="cyan")
+        console.print("  - On Termux: pkg install patch", style="cyan")
+    except subprocess.CalledProcessError as e:
+        console.print("❌ Failed to apply patch.", style="red")
+        console.print("The `patch` command failed. This may be due to a mismatch between the diff and the file content.", style="yellow")
+        if e.stderr:
+            console.print("Error details:", style="yellow")
+            console.print(e.stderr)
+    except Exception as e:
+        console.print(f"❌ An unexpected error occurred while applying the patch: {e}", style="red")
+
+
+def _interactive_file_selection(base_path: Path) -> Path | None:
+    """Prompts the user to select a file from the project."""
+    try:
+        all_files = find_files(base_path, ["**/*"])
+        choices = [p.relative_to(base_path).as_posix() for p in all_files]
+        if not choices:
+            console.print("No files found in the project.", style="yellow")
+            return None
+
+        question = {
+            "type": "fuzzy", "name": "file", "message": "Which file should this code be applied to?",
+            "choices": choices, "border": True
+        }
+        result = prompt([question], vi_mode=True)
+        return base_path / result.get("file") if result else None
+    except (InvalidArgument, IndexError, KeyError):
+        return None
+
+def apply_external_patch(content: str, base_path: Path):
+    """
+    Intelligently applies code updates from an external source.
+    Handles standard diffs, patchllm's format, and ambiguous code blocks.
+    """
+    if _is_diff_format(content):
+        console.print("Detected `diff` format. Attempting to apply with `patch`...", style="cyan")
+        _apply_diff(content, base_path)
+        return
+
+    clean_content = textwrap.dedent(content).strip()
+
+    parsed_blocks = _parse_file_blocks(clean_content)
+    if parsed_blocks:
+        console.print("Detected `patchllm` format. Applying changes...", style="cyan")
+        paste_response(clean_content)
+        return
+
+    console.print("Could not parse a standard format. Entering interactive mode...", style="yellow")
+    
+    code_block_match = re.search(r"```(?:\w+)?\s*\n(.*?)\n\s*```", clean_content, re.DOTALL)
+    if not code_block_match:
+        console.print("❌ No code blocks found in the input.", style="red")
+        return
+        
+    code_to_apply = code_block_match.group(1).strip()
+    target_file = _interactive_file_selection(base_path)
+
+    if not target_file:
+        console.print("Cancelled.", style="yellow")
+        return
+
+    response_for_diff = f"<file_path:{target_file.as_posix()}>\n```\n{code_to_apply}\n```"
+    diff_text = get_diff_for_file(str(target_file), response_for_diff)
+    console.print("\n--- Proposed Changes ---", style="bold yellow")
+    console.print(diff_text)
+    
+    try:
+        confirm_q = {"type": "confirm", "name": "confirm", "message": f"Apply these changes to '{target_file.name}'?", "default": True}
+        result = prompt([confirm_q])
+        if result and result.get("confirm"):
+            target_file.parent.mkdir(parents=True, exist_ok=True)
+            target_file.write_text(code_to_apply, encoding="utf-8")
+            console.print(f"✅ Updated [bold cyan]{target_file.name}[/bold cyan]", style="green")
+        else:
+            console.print("Cancelled.", style="yellow")
+    except (InvalidArgument, IndexError, KeyError):
+        console.print("Cancelled.", style="yellow")

patchllm/scopes/builder.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+from rich.console import Console
+
+from . import resolvers, structure, helpers
+from .constants import DEFAULT_EXCLUDE_EXTENSIONS
+
+console = Console()
+
+def build_context_from_files(file_paths: list[Path], base_path: Path) -> dict | None:
+    """Builds the context string directly from a provided list of file paths."""
+    if not file_paths:
+        console.print("\n⚠️  No files were provided to build the context.", style="yellow")
+        return None
+    return helpers._format_context(file_paths, [], base_path)
+
+def build_context(scope_name: str, scopes: dict, base_path: Path) -> dict | None:
+    """Builds the context string from files, handling static and dynamic scopes."""
+    if scope_name == "@structure":
+        return structure._build_structure_context(base_path)
+
+    relevant_files = []
+    urls = []
+
+    if scope_name.startswith('@'):
+        console.print(f"Resolving dynamic scope: [bold cyan]{scope_name}[/bold cyan]")
+        relevant_files = resolvers.resolve_dynamic_scope(scope_name, base_path)
+    else:
+        scope = scopes.get(scope_name)
+        if not scope:
+            console.print(f"❌ Static scope '{scope_name}' not found.", style="red")
+            return None
+        
+        scope_path = Path(scope.get("path", ".")).resolve()
+        include = scope.get("include_patterns", [])
+        exclude = scope.get("exclude_patterns", [])
+        search = scope.get("search_words", [])
+        urls = scope.get("urls", [])
+        
+        relevant_files = helpers.find_files(scope_path, include, exclude)
+        if search:
+            relevant_files = helpers.filter_files_by_keyword(relevant_files, search)
+
+    if not relevant_files and not urls:
+        console.print("\n⚠️  No files or URLs matched the specified criteria.", style="yellow")
+        return None
+
+    exclude_exts = scopes.get(scope_name, {}).get("exclude_extensions", DEFAULT_EXCLUDE_EXTENSIONS)
+    norm_ext = {ext.lower() for ext in exclude_exts}
+    relevant_files = [p for p in relevant_files if p.suffix.lower() not in norm_ext]
+
+    if not relevant_files and not urls:
+        console.print("\n⚠️  No files left after extension filtering.", style="yellow")
+        return None
+
+    return helpers._format_context(relevant_files, urls, base_path)