shotgun-sh 0.2.29.dev2__py3-none-any.whl → 0.6.1.dev1__py3-none-any.whl

shotgun/agents/tools/markdown_tools/insert_section.py

@@ -0,0 +1,148 @@
+"""Tool for inserting content into markdown sections."""
+
+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 (
+    find_and_validate_section,
+    get_heading_level,
+    load_markdown_file,
+    parse_section_number,
+    renumber_headings_after,
+    split_normalized_content,
+    write_markdown_file,
+)
+
+logger = get_logger(__name__)
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Inserting content",
+    key_arg="filename",
+    secondary_key_arg="new_heading",
+)
+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.
+
+    Note: If new_heading contains a section number (e.g., "### 4.4 New Section"),
+    subsequent numbered sections at the same level will be automatically incremented
+    to maintain proper numbering order.
+
+    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)
+
+        # Load and parse the markdown file
+        file_ctx = await load_markdown_file(file_path, filename)
+        if isinstance(file_ctx, str):
+            return file_ctx  # Error message
+
+        # Find and validate the target section
+        match = find_and_validate_section(file_ctx, after_heading)
+        if not match.is_success:
+            return match.error  # type: ignore[return-value]
+
+        # Build insert content
+        insert_content_lines = split_normalized_content(content)
+
+        # 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 match.end_line < len(file_ctx.lines):
+            insert_lines.append("")
+
+        # Insert before section end (before next heading or EOF)
+        new_lines = (
+            file_ctx.lines[: match.end_line]
+            + insert_lines
+            + file_ctx.lines[match.end_line :]
+        )
+
+        # If new_heading has a section number, renumber subsequent sections
+        if new_heading:
+            new_heading_level = get_heading_level(new_heading)
+            if new_heading_level:
+                section_num = parse_section_number(new_heading)
+                if section_num:
+                    # Calculate the line number where subsequent sections start
+                    # (after the inserted content)
+                    renumber_start = match.end_line + len(insert_lines)
+                    new_lines = renumber_headings_after(
+                        new_lines,
+                        start_line=renumber_start,
+                        heading_level=new_heading_level,
+                        increment=True,
+                    )
+
+        # Write the modified file
+        await write_markdown_file(file_ctx, new_lines)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.UPDATED)
+
+        logger.debug(
+            "Successfully inserted content into section '%s' in %s",
+            match.heading.text,  # type: ignore[union-attr]
+            filename,
+        )
+
+        lines_added = len(insert_lines)
+        confidence_display = f"{int(match.confidence * 100)}%"
+
+        if new_heading:
+            return (
+                f"Successfully inserted '{new_heading}' into '{match.heading.text}' in {filename} "  # type: ignore[union-attr]
+                f"(matched with {confidence_display} confidence, {lines_added} lines added)"
+            )
+        else:
+            return (
+                f"Successfully inserted content into '{match.heading.text}' in {filename} "  # type: ignore[union-attr]
+                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/agents/tools/markdown_tools/models.py

@@ -0,0 +1,86 @@
+"""Pydantic models for markdown tools."""
+
+from pathlib import Path
+
+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
+
+
+class SectionNumber(BaseModel):
+    """Parsed section number from a heading.
+
+    Examples:
+        - "## 3. Title" -> prefix="3", has_trailing_dot=True
+        - "### 4.4 Title" -> prefix="4.4", has_trailing_dot=False
+        - "#### 1.2.3.4 Title" -> prefix="1.2.3.4", has_trailing_dot=False
+    """
+
+    prefix: str  # The number part, e.g., "4.4" or "3"
+    has_trailing_dot: bool  # Whether it ends with a dot before the title
+
+
+class MarkdownFileContext(BaseModel):
+    """Context for a loaded markdown file ready for section operations.
+
+    This encapsulates the common state needed by all section manipulation tools:
+    file path, content split into lines, line ending style, and extracted headings.
+    """
+
+    file_path: Path
+    filename: str  # Original filename for error messages
+    lines: list[str]
+    line_ending: str
+    headings: HeadingList
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class SectionMatchResult(BaseModel):
+    """Result of finding and validating a section match.
+
+    Either contains a successful match with the heading and bounds,
+    or an error message explaining why the match failed.
+    """
+
+    # Success fields (all present when error is None)
+    heading: MarkdownHeading | None = None
+    confidence: float = 0.0
+    start_line: int = 0
+    end_line: int = 0
+
+    # Error field (present when match failed)
+    error: str | None = None
+
+    @property
+    def is_success(self) -> bool:
+        """Return True if this is a successful match."""
+        return self.error is None and self.heading is not None

shotgun/agents/tools/markdown_tools/remove_section.py

@@ -0,0 +1,114 @@
+"""Tool for removing markdown sections."""
+
+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 (
+    find_and_validate_section,
+    load_markdown_file,
+    parse_section_number,
+    renumber_headings_after,
+    write_markdown_file,
+)
+
+logger = get_logger(__name__)
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Removing section",
+    key_arg="filename",
+    secondary_key_arg="section_heading",
+)
+async def remove_markdown_section(
+    ctx: RunContext[AgentDeps],
+    filename: str,
+    section_heading: str,
+) -> str:
+    """Remove an entire section from a Markdown file.
+
+    Uses fuzzy matching on headings so minor typos are tolerated.
+    Removes from the target heading down to (but not including) the next
+    heading at the same or higher level.
+
+    Note: If the removed section has a numbered heading (e.g., "### 4.4 Title"),
+    subsequent numbered sections at the same level will be automatically
+    decremented to maintain proper numbering order.
+
+    Args:
+        ctx: Run context with agent dependencies
+        filename: Path to the Markdown file (relative to .shotgun directory)
+        section_heading: The heading to find and remove. Fuzzy matched.
+
+    Returns:
+        Success message or error message
+    """
+    logger.debug("Removing section '%s' from: %s", section_heading, filename)
+
+    try:
+        # Validate path with agent scoping
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
+
+        # Load and parse the markdown file
+        file_ctx = await load_markdown_file(file_path, filename)
+        if isinstance(file_ctx, str):
+            return file_ctx  # Error message
+
+        # Find and validate the target section
+        match = find_and_validate_section(file_ctx, section_heading)
+        if not match.is_success:
+            return match.error  # type: ignore[return-value]
+
+        removed_lines = match.end_line - match.start_line
+
+        # Check if the removed section has a numbered heading
+        section_num = parse_section_number(match.heading.text)  # type: ignore[union-attr]
+        heading_level = match.heading.level  # type: ignore[union-attr]
+
+        # Remove the section
+        new_lines = (
+            file_ctx.lines[: match.start_line] + file_ctx.lines[match.end_line :]
+        )
+
+        # If the removed section had a numbered heading, decrement subsequent sections
+        if section_num:
+            new_lines = renumber_headings_after(
+                new_lines,
+                start_line=match.start_line,
+                heading_level=heading_level,
+                increment=False,
+            )
+
+        # Write the modified file
+        await write_markdown_file(file_ctx, new_lines)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.UPDATED)
+
+        logger.debug(
+            "Successfully removed section '%s' from %s",
+            match.heading.text,  # type: ignore[union-attr]
+            filename,
+        )
+
+        confidence_display = f"{int(match.confidence * 100)}%"
+
+        return (
+            f"Successfully removed section '{match.heading.text}' from {filename} "  # type: ignore[union-attr]
+            f"(matched with {confidence_display} confidence, {removed_lines} lines removed)"
+        )
+
+    except ValueError as e:
+        # Path validation errors
+        error_msg = f"Error removing section from '{filename}': {e}"
+        logger.error("Section removal failed: %s", error_msg)
+        return error_msg
+
+    except Exception as e:
+        error_msg = f"Error removing section from '{filename}': {e}"
+        logger.error("Section removal failed: %s", error_msg)
+        return error_msg

shotgun/agents/tools/markdown_tools/replace_section.py

@@ -0,0 +1,119 @@
+"""Tool for replacing markdown sections."""
+
+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 (
+    find_and_validate_section,
+    load_markdown_file,
+    split_normalized_content,
+    write_markdown_file,
+)
+
+logger = get_logger(__name__)
+
+
+@register_tool(
+    category=ToolCategory.ARTIFACT_MANAGEMENT,
+    display_text="Replacing section",
+    key_arg="filename",
+    secondary_key_arg="section_heading",
+)
+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)
+
+        # Load and parse the markdown file
+        file_ctx = await load_markdown_file(file_path, filename)
+        if isinstance(file_ctx, str):
+            return file_ctx  # Error message
+
+        # Find and validate the target section
+        match = find_and_validate_section(file_ctx, section_heading)
+        if not match.is_success:
+            return match.error  # type: ignore[return-value]
+
+        old_section_lines = match.end_line - match.start_line
+
+        # Build new section
+        final_heading = new_heading if new_heading else match.heading.text  # type: ignore[union-attr]
+        new_content_lines = split_normalized_content(new_contents)
+
+        # 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 match.end_line < len(file_ctx.lines):
+            new_section_lines.append("")
+
+        # Replace section
+        new_lines = (
+            file_ctx.lines[: match.start_line]
+            + new_section_lines
+            + file_ctx.lines[match.end_line :]
+        )
+
+        # Write the modified file
+        await write_markdown_file(file_ctx, new_lines)
+
+        # Track the file operation
+        ctx.deps.file_tracker.add_operation(file_path, FileOperationType.UPDATED)
+
+        logger.debug(
+            "Successfully replaced section '%s' in %s",
+            match.heading.text,  # type: ignore[union-attr]
+            filename,
+        )
+
+        new_section_line_count = len(new_section_lines)
+        confidence_display = f"{int(match.confidence * 100)}%"
+
+        return (
+            f"Successfully replaced section '{match.heading.text}' in {filename} "  # type: ignore[union-attr]
+            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