teddy-cli 0.1.0__py3-none-any.whl

teddy_executor/core/domain/models/project_context.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass
+
+
+from typing import Dict, List, Optional
+
+
+from dataclasses import field
+
+
+@dataclass
+class ContextItem:
+    """
+    Metadata for a single context file.
+
+    Attributes:
+        path: The relative file path.
+        token_count: Estimated token size.
+        git_status: 2-char git status code.
+        scope: Source scope (System/Session/Turn).
+        selected: Whether the file is selected for the next turn.
+        auto_prune_reason: Reason for pre-deselection, if any.
+    """
+
+    path: str
+    token_count: int
+    git_status: str
+    scope: str
+    selected: bool = True
+    auto_prune_reason: Optional[str] = None
+
+
+@dataclass
+class ProjectContext:
+    """
+    A strictly-typed DTO representing the aggregated project context for display.
+
+    Attributes:
+        header: A string containing metadata about the context (e.g., CWD, OS).
+        content: The main body of the context (e.g., file tree and contents).
+        scoped_paths: A mapping of scope names (e.g., 'Turn', 'Session') to lists of file paths.
+        git_status: An optional string containing the output of 'git status -s'.
+        items: Structured list of context files and metadata.
+        agent_name: Name of the active agent.
+        system_prompt_tokens: Token count of the system prompt.
+        total_window: Total context window for the model.
+    """
+
+    header: str
+    content: str
+    scoped_paths: Dict[str, List[str]] = field(default_factory=dict)
+    git_status: Optional[str] = None
+    items: List[ContextItem] = field(default_factory=list)
+    agent_name: str = "Unknown"
+    system_prompt_tokens: int = 0
+    content_tokens: int = 0
+    total_window: int = 0

teddy_executor/core/domain/models/report_assembly_data.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional, Sequence
+
+from teddy_executor.core.domain.models import ActionLog, Plan
+
+
+@dataclass(frozen=True)
+class ReportAssemblyData:
+    """
+    DTO grouping parameters for ExecutionReport assembly.
+    """
+
+    plan: Plan
+    action_logs: Sequence[ActionLog]
+    start_time: datetime
+    message: Optional[str] = None
+    is_session: bool = False

teddy_executor/core/domain/models/session.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class SessionOptions:
+    """
+    Options for initializing a new session.
+    """
+
+    name: str
+    agent_name: str
+    initial_request: Optional[str] = None
+    additional_context: list[str] = field(default_factory=list)
+    model: Optional[str] = None
+    provider: Optional[str] = None
+    api_key: Optional[str] = None

teddy_executor/core/domain/models/shell_output.py

@@ -0,0 +1,12 @@
+from typing import TypedDict, NotRequired
+
+
+class ShellOutput(TypedDict):
+    """
+    A strictly-typed dictionary representing the result of a shell command execution.
+    """
+
+    stdout: str
+    stderr: str
+    return_code: int
+    failed_command: NotRequired[str]

teddy_executor/core/domain/models/web_search_results.py

@@ -0,0 +1,26 @@
+"""
+This module defines the strictly-typed data transfer object for web search results.
+"""
+
+from typing import List, TypedDict
+
+
+class SearchResult(TypedDict):
+    """Represents a single search result item."""
+
+    title: str
+    href: str
+    description: str  # The SERP snippet
+
+
+class QueryResult(TypedDict):
+    """Represents the results for a single search query."""
+
+    query: str
+    results: List[SearchResult]
+
+
+class WebSearchResults(TypedDict):
+    """Represents the aggregated results from one or more web search queries."""
+
+    query_results: List[QueryResult]

teddy_executor/core/ports/inbound/edit_simulator.py

@@ -0,0 +1,33 @@
+from typing import List, Protocol, TypedDict
+from teddy_executor.core.domain.models.plan import DEFAULT_SIMILARITY_THRESHOLD
+
+
+class EditPair(TypedDict, total=False):
+    find: str
+    replace: str
+    match_all: bool
+
+
+class IEditSimulator(Protocol):
+    """
+    Service for applying a sequence of FIND/REPLACE edits to a string.
+    """
+
+    def simulate_edits(
+        self,
+        content: str,
+        edits: List[EditPair],
+        threshold: float = DEFAULT_SIMILARITY_THRESHOLD,
+        match_all: bool = False,
+    ) -> tuple[str, list[float]]:
+        """
+        Applies each FIND/REPLACE pair in sequence to the provided content.
+
+        :param content: The original string content.
+        :param edits: A list of EditPair dictionaries.
+        :param threshold: The similarity threshold for fuzzy matching.
+        :param match_all: Global override for bulk replacement.
+        :return: A tuple of (transformed_string, list_of_similarity_scores).
+        :raises ValueError: If a FIND block is not found or is ambiguous (matches multiple times).
+        """
+        ...

teddy_executor/core/ports/inbound/get_context_use_case.py

@@ -0,0 +1,32 @@
+from typing import Dict, Optional, Protocol, Sequence
+from teddy_executor.core.domain.models import ProjectContext
+
+
+class IGetContextUseCase(Protocol):
+    """
+    Inbound Port for the Get Context use case.
+    This defines the contract for the primary entry point for gathering project context.
+    """
+
+    def get_context(
+        self,
+        context_files: Optional[Dict[str, Sequence[str]]] = None,
+        include_tokens: bool = True,
+        agent_name: str = "Unknown",
+        total_window: int = 0,
+        cache_dir: Optional[str] = None,
+        current_turn: Optional[str] = None,
+        system_prompt_tokens: int = 0,
+    ) -> ProjectContext:
+        """
+        Gathers all project context information.
+
+        Args:
+            context_files: Optional mapping of scope names to .context files.
+            current_turn: Optional 2-digit turn number to include in the header.
+            system_prompt_tokens: Token count of the system prompt (pre-computed).
+
+        Returns:
+            ProjectContext: A data object containing the aggregated context.
+        """
+        ...

teddy_executor/core/ports/inbound/init.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+
+
+class IInitUseCase(ABC):
+    """
+    Inbound port for project initialization.
+    """
+
+    @abstractmethod
+    def ensure_initialized(self) -> None:
+        """
+        Ensures the .teddy/ directory and its essential configuration
+        files are present in the current project root.
+        """
+        pass

teddy_executor/core/ports/inbound/plan_parser.py

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+
+from teddy_executor.core.domain.models import Plan
+
+
+from typing import Any, Optional, List
+
+
+class InvalidPlanError(Exception):
+    """Raised when the plan is malformed."""
+
+    def __init__(
+        self,
+        message: str,
+        offending_node: Optional[Any] = None,
+        offending_nodes: Optional[List[Any]] = None,
+        validation_errors: Optional[List[Any]] = None,
+    ):
+        super().__init__(message)
+        self.offending_nodes = offending_nodes or []
+        self.validation_errors = validation_errors or []
+        if offending_node:
+            self.offending_nodes.append(offending_node)
+
+    @property
+    def offending_node(self) -> Optional[Any]:
+        """Backward compatibility for single offending node."""
+        return self.offending_nodes[0] if self.offending_nodes else None
+
+
+class IPlanParser(ABC):
+    """
+    Defines the inbound port for parsing a plan from a raw string into a Plan object.
+    This is the contract that all plan parser implementations must adhere to.
+    """
+
+    @abstractmethod
+    def parse(self, plan_content: str, plan_path: Optional[str] = None) -> Plan:
+        """
+        Reads and parses the specified plan string into a structured Plan object.
+
+        Args:
+            plan_content: The raw string content of the plan.
+            plan_path: The optional path to the plan file for context detection.
+
+        Returns:
+            A Plan domain object.
+
+        Raises:
+            InvalidPlanError: If the plan content is malformed or invalid.
+        """
+        raise NotImplementedError

teddy_executor/core/ports/inbound/plan_reviewer.py

@@ -0,0 +1,44 @@
+from typing import Protocol, Optional, runtime_checkable, TYPE_CHECKING
+from teddy_executor.core.domain.models.plan import Plan
+
+if TYPE_CHECKING:
+    from teddy_executor.core.domain.models.plan import ActionData
+    from teddy_executor.core.domain.models.project_context import (
+        ProjectContext,
+    )  # vulture: ignore
+
+
+@runtime_checkable
+class IPlanReviewer(Protocol):
+    """
+    Inbound port for the interactive review and modification of a Plan.
+    """
+
+    def review(
+        self, plan: Plan, project_context: Optional["ProjectContext"] = None
+    ) -> Optional[Plan]:
+        """
+        Initiates the interactive review process.
+
+        Args:
+            plan: The plan to review.
+            project_context: Optional context metadata for display and auto-pruning.
+
+        Returns:
+            The modified Plan object, or None if the user cancels.
+        """
+        ...
+
+    def review_action(
+        self,
+        action: "ActionData",
+        total_actions: int,
+        agent_name: Optional[str] = None,
+    ) -> tuple[bool, str]:
+        """
+        Initiates a sequential interactive review for a single action.
+
+        Returns:
+            A tuple of (should_execute, captured_message).
+        """
+        ...

teddy_executor/core/ports/inbound/plan_validator.py

@@ -0,0 +1,26 @@
+"""
+This module defines the inbound port for plan validation.
+"""
+
+# Placeholder content
+# The Developer will implement this based on the design document.
+# See: docs/core/ports/inbound/plan_validator.md
+
+from abc import ABC, abstractmethod
+from typing import Dict, Optional, Sequence
+
+
+class IPlanValidator(ABC):
+    """
+    Defines the contract for any service that performs pre-flight validation of a Plan.
+    """
+
+    @abstractmethod
+    def validate(
+        self, plan, context_paths: Optional[Dict[str, Sequence[str]]] = None
+    ) -> list:
+        """
+        Validates the plan and returns a list of validation errors.
+        An empty list signifies a successful validation.
+        """
+        raise NotImplementedError

teddy_executor/core/ports/inbound/planning_use_case.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Optional, Sequence
+
+
+class IPlanningUseCase(ABC):
+    """
+    Defines the contract for generating an AI plan.
+    """
+
+    @abstractmethod
+    def generate_plan(
+        self,
+        user_message: Optional[str],
+        turn_dir: str,
+        context_files: Optional[Dict[str, Sequence[str]]] = None,
+    ) -> tuple[str, float]:
+        """
+        Generates a new plan.md file based on context and user message.
+
+        Args:
+            user_message: The instructions from the user.
+            turn_dir: The directory where artifacts for the turn are stored.
+            context_files: Optional scoped context files to include. If None,
+                implementations should auto-resolve session/turn manifests
+                from turn_dir.
+
+        Returns:
+            The path to the generated plan.md.
+        """
+        pass

teddy_executor/core/ports/inbound/run_plan_use_case.py

@@ -0,0 +1,60 @@
+from abc import ABC, abstractmethod
+from typing import Optional, TYPE_CHECKING
+from teddy_executor.core.domain.models import ExecutionReport, Plan
+
+if TYPE_CHECKING:
+    from teddy_executor.core.domain.models.project_context import ProjectContext
+
+
+class IRunPlanUseCase(ABC):
+    """
+    Defines the contract for running a teddy execution plan.
+    """
+
+    @abstractmethod
+    def execute(  # noqa: PLR0913
+        self,
+        plan: Optional[Plan] = None,
+        plan_content: Optional[str] = None,
+        plan_path: Optional[str] = None,
+        interactive: bool = True,
+        message: Optional[str] = None,
+        project_context: Optional["ProjectContext"] = None,
+    ) -> ExecutionReport:
+        """
+        Executes a plan and returns a report.
+
+        Args:
+            plan: An already parsed Plan object.
+            plan_content: Raw Markdown content of a plan.
+            plan_path: Path to a plan file on disk.
+            interactive: A flag to enable/disable step-by-step user approval.
+            message: Optional user instruction to include in the report.
+            project_context: Optional context metadata for display and auto-pruning.
+        """
+        _ = (plan, plan_content, plan_path, interactive, message, project_context)
+        raise NotImplementedError
+
+    @abstractmethod
+    def resume(
+        self,
+        session_name: str,
+        interactive: bool = True,
+        project_context: Optional["ProjectContext"] = None,
+    ) -> tuple[str, Optional[ExecutionReport]]:
+        """
+        Intelligently resumes the session based on its state.
+
+        Returns:
+            A tuple (actual_session_name, report). The actual_session_name
+            may differ from the input session_name after a centennial
+            migration (when the session transitions to a continuation name
+            like 'my-session-2').
+
+        Args:
+            session_name: The name of the session to resume.
+            interactive: Whether to run in interactive mode.
+            project_context: Optional context for the run.
+        """
+        _ = (session_name, interactive, project_context)
+        raise NotImplementedError

teddy_executor/core/ports/outbound/__init__.py

@@ -0,0 +1,34 @@
+from .config_service import IConfigService
+from .environment_inspector import IEnvironmentInspector
+from .file_system_manager import IFileSystemManager
+from .llm_client import ILlmClient, LlmApiError
+from .markdown_report_formatter import IMarkdownReportFormatter
+from .prompt_manager import IPromptManager
+from .repo_tree_generator import IRepoTreeGenerator
+from .session_loop_guard import ISessionLoopGuard
+from .session_manager import ISessionManager
+from .shell_executor import IShellExecutor
+from .system_environment import ISystemEnvironment
+from .time_service import ITimeService
+from .user_interactor import IUserInteractor
+from .web_scraper import WebScraper as IWebScraper
+from .web_searcher import IWebSearcher
+
+__all__ = [
+    "IConfigService",
+    "IEnvironmentInspector",
+    "IFileSystemManager",
+    "ILlmClient",
+    "IMarkdownReportFormatter",
+    "IPromptManager",
+    "IRepoTreeGenerator",
+    "ISessionLoopGuard",
+    "ISessionManager",
+    "IShellExecutor",
+    "ISystemEnvironment",
+    "ITimeService",
+    "IUserInteractor",
+    "IWebScraper",
+    "IWebSearcher",
+    "LlmApiError",
+]

teddy_executor/core/ports/outbound/config_service.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class IConfigService(ABC):
+    """
+    Interface for retrieving application configuration and secrets.
+    """
+
+    @abstractmethod
+    def get_config_path(self) -> str:
+        """
+        Returns the absolute or relative path to the configuration file.
+        """
+        pass
+
+    @abstractmethod
+    def get_setting(self, key: str, default: Optional[Any] = None) -> Optional[Any]:
+        """
+        Retrieves a configuration value by its key.
+
+        Args:
+            key: The configuration key to retrieve.
+            default: The default value to return if the key is not found.
+
+        Returns:
+            The configuration value, or the default value if not found.
+        """
+        pass

teddy_executor/core/ports/outbound/environment_inspector.py

@@ -0,0 +1,30 @@
+from typing import Protocol
+
+
+from typing import Optional
+
+
+class IEnvironmentInspector(Protocol):
+    """
+    Outbound Port for inspecting the user's environment (OS, terminal, etc.).
+    """
+
+    def get_environment_info(self) -> dict[str, str]:
+        """
+        Gathers key information about the system environment.
+
+        Returns:
+            dict[str, str]: A dictionary of environment properties.
+            Keys include: os_name, os_version, python_version, cwd, shell,
+            current_date (YYYY-MM-DD), current_time (HH:MM:SS).
+        """
+        ...
+
+    def get_git_status(self) -> Optional[str]:
+        """
+        Gathers the current Git status of the working directory.
+
+        Returns:
+            Optional[str]: The output of 'git status -s' or None if not a git repo.
+        """
+        ...

teddy_executor/core/ports/outbound/execution_report_assembler.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+
+from teddy_executor.core.domain.models import ExecutionReport, ReportAssemblyData
+
+
+class IExecutionReportAssembler(ABC):
+    """
+    Defines the outbound port for assembling an ExecutionReport and determining run status.
+    """
+
+    @abstractmethod
+    def assemble(
+        self,
+        data: ReportAssemblyData,
+    ) -> ExecutionReport:
+        """
+        Calculates the final run status and constructs a complete ExecutionReport.
+        """
+        raise NotImplementedError

teddy_executor/core/ports/outbound/file_system_manager.py

@@ -0,0 +1,131 @@
+from typing import Protocol, Sequence, TextIO
+
+
+class IFileSystemManager(Protocol):
+    """
+    An outbound port for interacting with a file system.
+    """
+
+    def path_exists(self, path: str) -> bool:
+        """
+        Checks if a path (file or directory) exists.
+        """
+        ...
+
+    def is_dir(self, path: str) -> bool:
+        """
+        Returns True if the path exists and is a directory.
+        """
+        ...
+
+    def list_directory_recursive(self, path: str) -> list[str]:
+        """
+        Lists all files in a directory and its subdirectories, respecting ignores.
+        """
+        ...
+
+    def create_directory(self, path: str) -> None:
+        """
+        Creates a directory, including any necessary parent directories.
+        """
+        ...
+
+    def write_file(self, path: str, content: str) -> None:
+        """
+        Writes content to a file, creating it if it doesn't exist
+        and overwriting it if it does.
+        """
+        ...
+
+    def create_file(self, path: str, content: str, overwrite: bool = False) -> None:
+        """
+        Creates a new file with the given content.
+
+        If overwrite is False (default), raises FileExistsError if the file already exists.
+        If overwrite is True, replaces existing file content.
+
+        Raises:
+            FileExistsError: If a file already exists and overwrite is False.
+        """
+        ...
+
+    def read_file(self, path: str) -> str:
+        """
+        Reads the content of a file from the specified path.
+
+        Raises:
+            FileNotFoundError: If no file exists at the specified path.
+        """
+        ...
+
+    def read_raw_file(self, path: str) -> str:
+        """
+        Reads the full, untruncated content of a file from the specified path.
+
+        Raises:
+            FileNotFoundError: If no file exists at the specified path.
+        """
+        ...
+
+    def edit_file(
+        self,
+        path: str,
+        edits: list[dict[str, str]],
+        similarity_threshold: float = 0.95,
+        match_all: bool = False,
+    ) -> list[float]:
+        """
+        Modifies an existing file by applying a list of find-and-replace blocks.
+
+        Raises:
+            FileNotFoundError: If no file exists at the specified path.
+        """
+        ...
+
+    def get_context_paths(self) -> list[str]:
+        """
+        Reads all .teddy/*.context files and returns a deduplicated list of paths.
+        """
+        ...
+
+    def resolve_paths_from_files(self, file_paths: Sequence[str]) -> list[str]:
+        """
+        Reads a list of context files and returns a deduplicated list of the paths they contain.
+        """
+        ...
+
+    def read_files_in_vault(self, paths: list[str]) -> dict[str, str | None]:
+        """
+        Reads the content of multiple files. Returns content for found files
+        and None for files that are not found.
+        """
+        ...
+
+    def list_directory(self, path: str) -> list[str]:
+        """
+        Lists the names of files and directories in the specified path.
+        """
+        ...
+
+    def get_mtime(self, path: str) -> float:
+        """
+        Returns the modification time of a file or directory as a timestamp.
+        """
+        ...
+
+    def move_directory(self, old_path: str, new_path: str) -> None:
+        """
+        Moves or renames a directory.
+        """
+        _ = old_path
+        ...
+
+    def open_file_for_append(self, path: str) -> TextIO:
+        """
+        Opens a file for appending, creating parent directories if needed.
+        Returns a TextIO file-like object for writing.
+
+        Raises:
+            IOError: If the file cannot be opened.
+        """
+        ...