shotgun-sh 0.5.2.dev2__tar.gz → 0.5.2.dev3__tar.gz

{shotgun_sh-0.5.2.dev2 → shotgun_sh-0.5.2.dev3}/.gitignore

@@ -5,7 +5,7 @@ tmp/
 playground/
 
 # Output directory
-.shotgun/
+.shotgun*
 
 # Generated build files
 src/shotgun/build_constants.py

{shotgun_sh-0.5.2.dev2 → shotgun_sh-0.5.2.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgun-sh
-Version: 0.5.2.dev2
+Version: 0.5.2.dev3
 Summary: AI-powered research, planning, and task management CLI tool
 Project-URL: Homepage, https://shotgun.sh/
 Project-URL: Repository, https://github.com/shotgun-sh/shotgun

{shotgun_sh-0.5.2.dev2 → shotgun_sh-0.5.2.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shotgun-sh"
-version = "0.5.2.dev2"
+version = "0.5.2.dev3"
 description = "AI-powered research, planning, and task management CLI tool"
 readme = "README.md"
 license = { text = "MIT" }

{shotgun_sh-0.5.2.dev2 → shotgun_sh-0.5.2.dev3}/src/shotgun/agents/common.py

@@ -38,8 +38,10 @@ from .tools import (
     codebase_shell,
     directory_lister,
     file_read,
+    insert_markdown_section,
     query_graph,
     read_file,
+    replace_markdown_section,
     retrieve_code,
     write_file,
 )
@@ -204,6 +206,8 @@ async def create_base_agent(
     agent.tool(write_file)
     agent.tool(append_file)
     agent.tool(read_file)
+    agent.tool(replace_markdown_section)
+    agent.tool(insert_markdown_section)
 
     # Register codebase understanding tools (conditional)
     if load_codebase_understanding_tools:

{shotgun_sh-0.5.2.dev2 → shotgun_sh-0.5.2.dev3}/src/shotgun/agents/tools/__init__.py

@@ -8,6 +8,7 @@ from .codebase import (
     retrieve_code,
 )
 from .file_management import append_file, read_file, write_file
+from .markdown_tools import insert_markdown_section, replace_markdown_section
 from .web_search import (
     anthropic_web_search_tool,
     gemini_web_search_tool,
@@ -23,6 +24,8 @@ __all__ = [
     "read_file",
     "write_file",
     "append_file",
+    "replace_markdown_section",
+    "insert_markdown_section",
     # Codebase understanding tools
     "query_graph",
     "retrieve_code",

shotgun_sh-0.5.2.dev3/src/shotgun/agents/tools/markdown_tools/__init__.py

@@ -0,0 +1,33 @@
+"""Markdown manipulation tools for Pydantic AI agents."""
+
+from .insert_section import insert_markdown_section
+from .models import CloseMatch, HeadingList, HeadingMatch, MarkdownHeading
+from .replace_section import replace_markdown_section
+from .utils import (
+    detect_line_ending,
+    extract_headings,
+    find_close_matches,
+    find_matching_heading,
+    find_section_bounds,
+    get_heading_level,
+    normalize_section_content,
+)
+
+__all__ = [
+    # Tools
+    "replace_markdown_section",
+    "insert_markdown_section",
+    # Models
+    "MarkdownHeading",
+    "HeadingList",
+    "HeadingMatch",
+    "CloseMatch",
+    # Utilities
+    "get_heading_level",
+    "extract_headings",
+    "find_matching_heading",
+    "find_close_matches",
+    "find_section_bounds",
+    "detect_line_ending",
+    "normalize_section_content",
+]

shotgun_sh-0.5.2.dev3/src/shotgun/agents/tools/markdown_tools/insert_section.py

@@ -0,0 +1,195 @@
+"""Tool for inserting content into markdown sections."""
+
+import aiofiles
+import aiofiles.os
+from pydantic_ai import RunContext
+
+from shotgun.agents.models import AgentDeps, FileOperationType
+from shotgun.agents.tools.file_management import _validate_agent_scoped_path
+from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.logging_config import get_logger
+
+from .utils import (
+    detect_line_ending,
+    extract_headings,
+    find_close_matches,
+    find_matching_heading,
+    find_section_bounds,
+    normalize_section_content,
+)
+
+logger = get_logger(__name__)
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Inserting content",
+    key_arg="filename",
+)
+async def insert_markdown_section(
+    ctx: RunContext[AgentDeps],
+    filename: str,
+    after_heading: str,
+    content: str,
+    new_heading: str | None = None,
+) -> str:
+    """Insert content at the end of a Markdown section.
+
+    PREFER THIS TOOL over rewriting the entire file - it is faster, less costly,
+    and less error-prone. Use this to append content to an existing section.
+
+    Uses fuzzy matching on headings so minor typos are tolerated.
+    Inserts content just before the next heading at the same or higher level.
+
+    Args:
+        ctx: Run context with agent dependencies
+        filename: Path to the Markdown file (relative to .shotgun directory)
+        after_heading: The heading to insert after (e.g., '## Requirements'). Fuzzy matched.
+        content: The content to insert at the end of the section
+        new_heading: Optional heading for the inserted content (creates a subsection)
+
+    Returns:
+        Success message or error message
+    """
+    logger.debug("Inserting content into section '%s' in: %s", after_heading, filename)
+
+    try:
+        # Validate path with agent scoping
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
+
+        # Check if file exists
+        if not await aiofiles.os.path.exists(file_path):
+            return f"Error: File '{filename}' not found"
+
+        # Read file content (newline="" preserves original line endings)
+        async with aiofiles.open(file_path, encoding="utf-8", newline="") as f:
+            file_content = await f.read()
+
+        # Detect line ending style
+        line_ending = detect_line_ending(file_content)
+        lines = file_content.split("\n")
+
+        # Remove \r from lines if CRLF
+        if line_ending == "\r\n":
+            lines = [line.rstrip("\r") for line in lines]
+
+        # Extract headings
+        headings = extract_headings(file_content)
+
+        if not headings:
+            return f"Error: No headings found in '{filename}'. Cannot insert into files without headings."
+
+        # Find matching heading
+        match_result = find_matching_heading(headings, after_heading)
+
+        if match_result is None:
+            # No match found - provide helpful error with available headings
+            available = [h.text for h in headings]
+            close = find_close_matches(headings, after_heading)
+
+            if close and close[0].confidence >= 0.6:
+                # There are close matches but below threshold
+                close_display = ", ".join(
+                    f"'{m.heading_text}' ({int(m.confidence * 100)}%)" for m in close
+                )
+                return (
+                    f"No section matching '{after_heading}' found in {filename}. "
+                    f"Did you mean: {close_display}"
+                )
+            else:
+                # List available headings
+                available_display = ", ".join(available[:5])
+                if len(available) > 5:
+                    available_display += f" (+{len(available) - 5} more)"
+                return (
+                    f"No section matching '{after_heading}' found in {filename}. "
+                    f"Available headings: {available_display}"
+                )
+
+        matched = match_result.heading
+        confidence = match_result.confidence
+
+        # Check for ambiguous matches (multiple close matches)
+        if confidence < 1.0:
+            close = find_close_matches(
+                headings, after_heading, threshold=confidence - 0.1
+            )
+            if len(close) > 1 and close[1].confidence >= confidence - 0.05:
+                # Second match is very close to first - ambiguous
+                close_display = ", ".join(
+                    f"'{m.heading_text}' ({int(m.confidence * 100)}%)"
+                    for m in close[:3]
+                )
+                return (
+                    f"Multiple sections closely match '{after_heading}' in {filename}: "
+                    f"{close_display}. Please be more specific."
+                )
+
+        # Find section boundaries
+        _start_line, end_line = find_section_bounds(
+            lines, matched.line_number, matched.level
+        )
+
+        # Build insert content
+        normalized_content = normalize_section_content(content)
+        insert_content_lines = normalized_content.split("\n")
+        # Remove empty last line from split (since we added \n)
+        if insert_content_lines and insert_content_lines[-1] == "":
+            insert_content_lines.pop()
+
+        # Build the insert lines
+        insert_lines: list[str] = [""]  # Blank line separator before new content
+
+        if new_heading:
+            insert_lines.append(new_heading)
+            insert_lines.append("")  # Blank line after heading
+
+        insert_lines.extend(insert_content_lines)
+
+        # Add trailing blank line if not at EOF
+        if end_line < len(lines):
+            insert_lines.append("")
+
+        # Insert before section end (before next heading or EOF)
+        new_lines = lines[:end_line] + insert_lines + lines[end_line:]
+
+        # Join with detected line ending
+        new_content = line_ending.join(new_lines)
+
+        # Write file (newline="" preserves our chosen line endings)
+        async with aiofiles.open(file_path, "w", encoding="utf-8", newline="") as f:
+            await f.write(new_content)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.UPDATED)
+
+        logger.debug(
+            "Successfully inserted content into section '%s' in %s",
+            matched.text,
+            filename,
+        )
+
+        lines_added = len(insert_lines)
+        confidence_display = f"{int(confidence * 100)}%"
+
+        if new_heading:
+            return (
+                f"Successfully inserted '{new_heading}' into '{matched.text}' in {filename} "
+                f"(matched with {confidence_display} confidence, {lines_added} lines added)"
+            )
+        else:
+            return (
+                f"Successfully inserted content into '{matched.text}' in {filename} "
+                f"(matched with {confidence_display} confidence, {lines_added} lines added)"
+            )
+
+    except ValueError as e:
+        # Path validation errors
+        error_msg = f"Error inserting into '{filename}': {e}"
+        logger.error("Section insertion failed: %s", error_msg)
+        return error_msg
+
+    except Exception as e:
+        error_msg = f"Error inserting into '{filename}': {e}"
+        logger.error("Section insertion failed: %s", error_msg)
+        return error_msg

shotgun_sh-0.5.2.dev3/src/shotgun/agents/tools/markdown_tools/models.py

@@ -0,0 +1,33 @@
+"""Pydantic models for markdown tools."""
+
+from pydantic import BaseModel
+
+
+class MarkdownHeading(BaseModel):
+    """Represents a heading found in a Markdown file."""
+
+    line_number: int
+    text: str
+    level: int
+
+    @property
+    def normalized_text(self) -> str:
+        """Return heading text without # prefix, stripped and lowercased."""
+        return self.text.lstrip("#").strip().lower()
+
+
+HeadingList = list[MarkdownHeading]
+
+
+class HeadingMatch(BaseModel):
+    """Result of a successful heading match."""
+
+    heading: MarkdownHeading
+    confidence: float
+
+
+class CloseMatch(BaseModel):
+    """A close match result for error messages."""
+
+    heading_text: str
+    confidence: float

shotgun_sh-0.5.2.dev3/src/shotgun/agents/tools/markdown_tools/replace_section.py

@@ -0,0 +1,186 @@
+"""Tool for replacing markdown sections."""
+
+import aiofiles
+import aiofiles.os
+from pydantic_ai import RunContext
+
+from shotgun.agents.models import AgentDeps, FileOperationType
+from shotgun.agents.tools.file_management import _validate_agent_scoped_path
+from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.logging_config import get_logger
+
+from .utils import (
+    detect_line_ending,
+    extract_headings,
+    find_close_matches,
+    find_matching_heading,
+    find_section_bounds,
+    normalize_section_content,
+)
+
+logger = get_logger(__name__)
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Replacing section",
+    key_arg="filename",
+)
+async def replace_markdown_section(
+    ctx: RunContext[AgentDeps],
+    filename: str,
+    section_heading: str,
+    new_contents: str,
+    new_heading: str | None = None,
+) -> str:
+    """Replace an entire section in a Markdown file.
+
+    PREFER THIS TOOL over rewriting the entire file - it is faster, less costly,
+    and less error-prone.
+
+    Uses fuzzy matching on headings so minor typos are tolerated.
+    Replaces from the target heading down to (but not including) the next
+    heading at the same or higher level.
+
+    Args:
+        ctx: Run context with agent dependencies
+        filename: Path to the Markdown file (relative to .shotgun directory)
+        section_heading: The heading to find (e.g., '## Requirements'). Fuzzy matched.
+        new_contents: The new content for the section body (not including the heading)
+        new_heading: Optional new heading text to replace the old one
+
+    Returns:
+        Success message or error message
+    """
+    logger.debug("Replacing section '%s' in: %s", section_heading, filename)
+
+    try:
+        # Validate path with agent scoping
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
+
+        # Check if file exists
+        if not await aiofiles.os.path.exists(file_path):
+            return f"Error: File '{filename}' not found"
+
+        # Read file content (newline="" preserves original line endings)
+        async with aiofiles.open(file_path, encoding="utf-8", newline="") as f:
+            content = await f.read()
+
+        # Detect line ending style
+        line_ending = detect_line_ending(content)
+        lines = content.split("\n")
+
+        # Remove \r from lines if CRLF
+        if line_ending == "\r\n":
+            lines = [line.rstrip("\r") for line in lines]
+
+        # Extract headings
+        headings = extract_headings(content)
+
+        if not headings:
+            return f"Error: No headings found in '{filename}'. Cannot replace sections in files without headings."
+
+        # Find matching heading
+        match_result = find_matching_heading(headings, section_heading)
+
+        if match_result is None:
+            # No match found - provide helpful error with available headings
+            available = [h.text for h in headings]
+            close = find_close_matches(headings, section_heading)
+
+            if close and close[0].confidence >= 0.6:
+                # There are close matches but below threshold
+                close_display = ", ".join(
+                    f"'{m.heading_text}' ({int(m.confidence * 100)}%)" for m in close
+                )
+                return (
+                    f"No section matching '{section_heading}' found in {filename}. "
+                    f"Did you mean: {close_display}"
+                )
+            else:
+                # List available headings
+                available_display = ", ".join(available[:5])
+                if len(available) > 5:
+                    available_display += f" (+{len(available) - 5} more)"
+                return (
+                    f"No section matching '{section_heading}' found in {filename}. "
+                    f"Available headings: {available_display}"
+                )
+
+        matched = match_result.heading
+        confidence = match_result.confidence
+
+        # Check for ambiguous matches (multiple close matches)
+        if confidence < 1.0:
+            close = find_close_matches(
+                headings, section_heading, threshold=confidence - 0.1
+            )
+            if len(close) > 1 and close[1].confidence >= confidence - 0.05:
+                # Second match is very close to first - ambiguous
+                close_display = ", ".join(
+                    f"'{m.heading_text}' ({int(m.confidence * 100)}%)"
+                    for m in close[:3]
+                )
+                return (
+                    f"Multiple sections closely match '{section_heading}' in {filename}: "
+                    f"{close_display}. Please be more specific."
+                )
+
+        # Find section boundaries
+        start_line, end_line = find_section_bounds(
+            lines, matched.line_number, matched.level
+        )
+        old_section_lines = end_line - start_line
+
+        # Build new section
+        final_heading = new_heading if new_heading else matched.text
+        normalized_content = normalize_section_content(new_contents)
+
+        # Split new content into lines
+        new_content_lines = normalized_content.split("\n")
+        # Remove empty last line from split (since we added \n)
+        if new_content_lines and new_content_lines[-1] == "":
+            new_content_lines.pop()
+
+        # Build the new section: heading + blank line + content
+        new_section_lines = [final_heading, ""]
+        new_section_lines.extend(new_content_lines)
+
+        # Add trailing blank line if not at EOF
+        if end_line < len(lines):
+            new_section_lines.append("")
+
+        # Replace section
+        new_lines = lines[:start_line] + new_section_lines + lines[end_line:]
+
+        # Join with detected line ending
+        new_content = line_ending.join(new_lines)
+
+        # Write file (newline="" preserves our chosen line endings)
+        async with aiofiles.open(file_path, "w", encoding="utf-8", newline="") as f:
+            await f.write(new_content)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.UPDATED)
+
+        logger.debug("Successfully replaced section '%s' in %s", matched.text, filename)
+
+        new_section_line_count = len(new_section_lines)
+        confidence_display = f"{int(confidence * 100)}%"
+
+        return (
+            f"Successfully replaced section '{matched.text}' in {filename} "
+            f"(matched with {confidence_display} confidence, "
+            f"{old_section_lines} lines -> {new_section_line_count} lines)"
+        )
+
+    except ValueError as e:
+        # Path validation errors
+        error_msg = f"Error replacing section in '{filename}': {e}"
+        logger.error("Section replacement failed: %s", error_msg)
+        return error_msg
+
+    except Exception as e:
+        error_msg = f"Error replacing section in '{filename}': {e}"
+        logger.error("Section replacement failed: %s", error_msg)
+        return error_msg

shotgun_sh-0.5.2.dev3/src/shotgun/agents/tools/markdown_tools/utils.py

@@ -0,0 +1,157 @@
+"""Utility functions for markdown parsing and manipulation."""
+
+import re
+from difflib import SequenceMatcher
+
+from .models import CloseMatch, HeadingList, HeadingMatch, MarkdownHeading
+
+
+def get_heading_level(line: str) -> int | None:
+    """Get the heading level (1-6) from a line, or None if not a heading.
+
+    Args:
+        line: A line of text to check
+
+    Returns:
+        The heading level (1-6) or None if not a heading
+    """
+    match = re.match(r"^(#{1,6})\s+", line)
+    return len(match.group(1)) if match else None
+
+
+def extract_headings(content: str) -> HeadingList:
+    """Extract all headings from markdown content.
+
+    Args:
+        content: The markdown content to parse
+
+    Returns:
+        List of MarkdownHeading objects
+    """
+    headings: HeadingList = []
+    for i, line in enumerate(content.splitlines()):
+        level = get_heading_level(line)
+        if level is not None:
+            headings.append(MarkdownHeading(line_number=i, text=line, level=level))
+    return headings
+
+
+def find_matching_heading(
+    headings: HeadingList,
+    target: str,
+    threshold: float = 0.8,
+) -> HeadingMatch | None:
+    """Find the best matching heading above the similarity threshold.
+
+    Args:
+        headings: List of MarkdownHeading objects
+        target: The target heading to match (e.g., "## Requirements")
+        threshold: Minimum similarity ratio (0.0-1.0)
+
+    Returns:
+        HeadingMatch with the matched heading and confidence, or None if no match
+    """
+    best_heading: MarkdownHeading | None = None
+    best_ratio = 0.0
+
+    # Normalize target: strip leading #s and whitespace, lowercase
+    norm_target = target.lstrip("#").strip().lower()
+
+    for heading in headings:
+        ratio = SequenceMatcher(None, heading.normalized_text, norm_target).ratio()
+
+        if ratio > best_ratio and ratio >= threshold:
+            best_ratio = ratio
+            best_heading = heading
+
+    if best_heading is not None:
+        return HeadingMatch(heading=best_heading, confidence=best_ratio)
+    return None
+
+
+def find_close_matches(
+    headings: HeadingList,
+    target: str,
+    threshold: float = 0.6,
+    max_matches: int = 3,
+) -> list[CloseMatch]:
+    """Find headings that are close matches to the target.
+
+    Used for error messages when no exact match is found.
+
+    Args:
+        headings: List of MarkdownHeading objects
+        target: The target heading to match
+        threshold: Minimum similarity ratio for inclusion
+        max_matches: Maximum number of matches to return
+
+    Returns:
+        List of CloseMatch objects, sorted by confidence descending
+    """
+    norm_target = target.lstrip("#").strip().lower()
+    matches: list[CloseMatch] = []
+
+    for heading in headings:
+        ratio = SequenceMatcher(None, heading.normalized_text, norm_target).ratio()
+        if ratio >= threshold:
+            matches.append(CloseMatch(heading_text=heading.text, confidence=ratio))
+
+    # Sort by confidence descending
+    matches.sort(key=lambda x: x.confidence, reverse=True)
+    return matches[:max_matches]
+
+
+def find_section_bounds(
+    lines: list[str],
+    heading_line_num: int,
+    heading_level: int,
+) -> tuple[int, int]:
+    """Find the boundaries of a section.
+
+    The section includes everything from the heading to the next heading
+    at the same or higher level (exclusive), or end of file.
+
+    Args:
+        lines: All lines of the file
+        heading_line_num: Line number of the section heading
+        heading_level: Level of the section heading (1-6)
+
+    Returns:
+        Tuple of (start_line, end_line) where end_line is exclusive
+    """
+    start = heading_line_num
+    end = len(lines)  # Default to EOF
+
+    for i in range(heading_line_num + 1, len(lines)):
+        level = get_heading_level(lines[i])
+        if level is not None and level <= heading_level:
+            end = i
+            break
+
+    return (start, end)
+
+
+def detect_line_ending(content: str) -> str:
+    """Detect the line ending style used in the content.
+
+    Args:
+        content: The file content
+
+    Returns:
+        The line ending string ('\\r\\n' or '\\n')
+    """
+    if "\r\n" in content:
+        return "\r\n"
+    return "\n"
+
+
+def normalize_section_content(content: str) -> str:
+    """Normalize content to have no leading whitespace and single trailing newline.
+
+    Args:
+        content: The content to normalize
+
+    Returns:
+        Normalized content
+    """
+    return content.strip() + "\n"