cortexshift 0.1.0__py3-none-any.whl

cortexshift/ports/process_runner.py

@@ -0,0 +1,31 @@
+"""Port defining the interface for running interactive provider processes."""
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class InteractiveProcessRunner(Protocol):
+    """Abstract port for running long-lived interactive provider processes.
+
+    Unlike diagnostic command runners, interactive runners inherit terminal
+    streams (stdin, stdout, stderr) and do not impose short timeouts.
+    """
+
+    def run_interactive(
+        self,
+        argv: list[str],
+        cwd: Path | str,
+        env: dict[str, str] | None = None,
+    ) -> int:
+        """Run a process interactively inheriting the terminal.
+
+        Args:
+            argv: Argument vector to execute without a shell.
+            cwd: Canonical working directory for execution.
+            env: Optional environment dictionary overlay.
+
+        Returns:
+            The exit code of the terminated process.
+        """
+        ...

cortexshift/ports/provider.py

@@ -0,0 +1,152 @@
+"""Port defining the interface for AI coding agent provider adapters."""
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from cortexshift.domain.handoff import HandoffRecord
+from cortexshift.domain.launch import LaunchSpecification
+from cortexshift.domain.mcp_binding import McpSessionBinding
+from cortexshift.domain.provider import ProviderCapabilities, ProviderId
+from cortexshift.domain.task import Task
+
+
+@runtime_checkable
+class ProviderAdapter(Protocol):
+    """Abstract port for orchestrating an AI coding agent CLI.
+
+    Concrete implementations wrap native provider CLIs (e.g. Claude Code,
+    Codex, Antigravity) without polluting the core domain with vendor specifics.
+    """
+
+    @property
+    def provider_id(self) -> ProviderId:
+        """The stable unique identifier for this provider."""
+        ...
+
+    def probe(self) -> bool:
+        """Check whether the native CLI is installed, licensed, and executable."""
+        ...
+
+    def get_capabilities(self) -> ProviderCapabilities:
+        """Return the declared operational capabilities of this provider."""
+        ...
+
+    def launch_interactive(
+        self,
+        task: Task,
+        handoff: HandoffRecord | None = None,
+    ) -> int:
+        """Launch an interactive terminal session with this provider on the given task.
+
+        Args:
+            task: The persistent task being worked on.
+            handoff: Advisory handoff payload if transitioning from another agent.
+
+        Returns:
+            Exit code of the process.
+        """
+        ...
+
+    def run_headless(
+        self,
+        task: Task,
+        instruction: str,
+        handoff: HandoffRecord | None = None,
+    ) -> int:
+        """Run a non-interactive single-command session if supported.
+
+        Args:
+            task: The persistent task being worked on.
+            instruction: Prompt or command to execute.
+            handoff: Advisory handoff payload if available.
+
+        Returns:
+            Exit code of the process.
+        """
+        ...
+
+    def resume_native_session(
+        self,
+        task: Task,
+        native_session_id: str,
+    ) -> int:
+        """Resume a previous provider-native session if supported.
+
+        Args:
+            task: The persistent task being worked on.
+            native_session_id: Provider's internal thread or session ID.
+
+        Returns:
+            Exit code of the process.
+        """
+        ...
+
+
+@runtime_checkable
+class ProviderRuntimeAdapter(Protocol):
+    """Port for building provider launch specifications without invoking processes directly."""
+
+    @property
+    def provider_id(self) -> ProviderId:
+        """Canonical provider identifier."""
+        ...
+
+    @property
+    def display_name(self) -> str:
+        """Human-readable display name."""
+        ...
+
+    @property
+    def executable(self) -> str:
+        """Base name of the provider CLI executable."""
+        ...
+
+    def get_capabilities(self) -> ProviderCapabilities:
+        """Return declared operational capabilities of this provider."""
+        ...
+
+    def build_launch_spec(
+        self,
+        project_root: Path,
+        executable_path: str,
+        prompt: str | None = None,
+    ) -> LaunchSpecification:
+        """Build concrete launch specification for this provider.
+
+        Args:
+            project_root: Absolute project root directory to serve as cwd.
+            executable_path: Resolved absolute or PATH path to the executable.
+            prompt: Optional initial prompt.
+
+        Returns:
+            A validated LaunchSpecification.
+
+        Raises:
+            UnsupportedPromptError: If prompt is provided but not supported for interactive launch.
+        """
+        ...
+
+
+@runtime_checkable
+class ManagedMcpBinder(Protocol):
+    """Optional port for providers that configure the CortexShift MCP server per launch.
+
+    A provider CLI spawns the MCP server itself, so CortexShift cannot rely on its own
+    process environment reaching that grandchild: Codex, for one, sanitizes it. Providers
+    implementing this port restate the trusted binding inside the MCP configuration they
+    were launched with. Providers configured out of band, such as Antigravity's workspace
+    file, implement nothing and keep their existing behaviour.
+    """
+
+    def bind_managed_mcp(
+        self,
+        launch_spec: LaunchSpecification,
+        binding: McpSessionBinding,
+    ) -> LaunchSpecification:
+        """Return the launch specification with the managed binding declared to MCP.
+
+        Implementations must be total: a specification carrying no CortexShift MCP
+        configuration, or one belonging to another provider, is returned unchanged rather
+        than rejected.
+        """
+        ...

cortexshift/ports/repository.py

@@ -0,0 +1,44 @@
+"""Port defining repository inspection and snapshot persistence capabilities."""
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from cortexshift.domain.git import GitSnapshot, RepositoryInspection
+
+
+@runtime_checkable
+class RepositoryInspector(Protocol):
+    """Abstract port for inspecting the repository filesystem and Git status.
+
+    Extracts empirical repository state without embedding shell or git specifics
+    into core domain logic.
+    """
+
+    def inspect(self, project_root: Path | str, project_id: str = "") -> RepositoryInspection:
+        """Inspect the repository and return a RepositoryInspection domain model.
+
+        Args:
+            project_root: Absolute path to the CortexShift project root directory.
+            project_id: Canonical identifier of the containing Project.
+
+        Returns:
+            A populated RepositoryInspection domain model.
+        """
+        ...
+
+
+@runtime_checkable
+class RepositorySnapshotStore(Protocol):
+    """Abstract port for persisting and retrieving Git snapshots."""
+
+    def save_snapshot(self, snapshot: GitSnapshot) -> None:
+        """Persist a GitSnapshot."""
+        ...
+
+    def get_snapshot(self, snapshot_id: str) -> GitSnapshot | None:
+        """Retrieve a GitSnapshot by its unique identifier."""
+        ...
+
+    def list_snapshots(self, project_id: str, limit: int = 10) -> list[GitSnapshot]:
+        """List snapshots for a given project, ordered newest first."""
+        ...

cortexshift/ports/session_store.py

@@ -0,0 +1,27 @@
+"""Port defining persistence boundaries for CortexShift agent sessions."""
+
+from typing import Protocol, runtime_checkable
+
+from cortexshift.domain.session import Session
+
+
+@runtime_checkable
+class SessionStore(Protocol):
+    """Abstract port for persisting and querying CortexShift agent execution sessions."""
+
+    def save_session(self, session: Session) -> None:
+        """Persist or update a Session record."""
+        ...
+
+    def get_session(self, session_id: str) -> Session | None:
+        """Retrieve a Session by its stable identifier."""
+        ...
+
+    def list_sessions(
+        self,
+        project_id: str | None = None,
+        task_id: str | None = None,
+        limit: int | None = 20,
+    ) -> list[Session]:
+        """List sessions, ordered newest first."""
+        ...

cortexshift/ports/state_store.py

@@ -0,0 +1,55 @@
+"""Port defining persistence boundaries for CortexShift state."""
+
+from typing import Protocol, runtime_checkable
+
+from cortexshift.domain.project import Project
+from cortexshift.domain.task import Task
+
+
+@runtime_checkable
+class StateStore(Protocol):
+    """Abstract port for persisting and querying CortexShift entities.
+
+    Isolates domain and application logic from the underlying storage mechanism
+    (e.g., local SQLite, in-memory test store).
+    """
+
+    # Project operations
+    def save_project(self, project: Project) -> None:
+        """Persist or update a Project."""
+        ...
+
+    def get_project(self, project_id: str) -> Project | None:
+        """Retrieve a Project by its stable identifier."""
+        ...
+
+    def get_default_project(self) -> Project | None:
+        """Retrieve the canonical project associated with this project-local store."""
+        ...
+
+    # Task operations
+    def save_task(self, task: Task) -> None:
+        """Persist or update a Task."""
+        ...
+
+    def get_task(self, task_id: str) -> Task | None:
+        """Retrieve a Task by its stable identifier."""
+        ...
+
+    def list_tasks(self, project_id: str) -> list[Task]:
+        """List all tasks associated with a given project."""
+        ...
+
+    # Runtime / Active Task state
+    def get_active_task_id(self, project_id: str) -> str | None:
+        """Retrieve the identifier of the active task for the project, if any."""
+        ...
+
+    def set_active_task_id(self, project_id: str, task_id: str | None) -> None:
+        """Set or clear the active task identifier for the project."""
+        ...
+
+    # Schema inspection
+    def get_schema_version(self) -> int:
+        """Retrieve the current applied database schema version."""
+        ...

cortexshift/ports/workspace_lease.py

@@ -0,0 +1,39 @@
+"""Port defining exclusive workspace leasing to enforce single mutating agent invariant."""
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WorkspaceLease(Protocol):
+    """An acquired or acquirable exclusive lease on a CortexShift workspace."""
+
+    @property
+    def lock_path(self) -> Path:
+        """The absolute path to the lock file."""
+        ...
+
+    def acquire(self) -> bool:
+        """Attempt to acquire the exclusive non-blocking lease.
+
+        Returns:
+            True if the lease was acquired successfully, False if already held.
+        """
+        ...
+
+    def release(self) -> None:
+        """Release the held exclusive lease."""
+        ...
+
+    def is_locked(self) -> bool:
+        """Check whether the workspace is currently locked by any process."""
+        ...
+
+
+@runtime_checkable
+class WorkspaceLeaseManager(Protocol):
+    """Factory port for creating workspace lease instances for a project."""
+
+    def get_lease(self, project_root: Path) -> WorkspaceLease:
+        """Return a WorkspaceLease configured for the given project root."""
+        ...

cortexshift/tui/__init__.py

@@ -0,0 +1,24 @@
+"""CortexShift interactive terminal control center (Textual).
+
+The TUI is an adapter over the existing application services — the same services the CLI
+and the MCP server use. It owns presentation only: no SQL, no SQLite handles, no Git
+subprocesses, no provider argv construction, and no duplicated task, recovery, or handoff
+rules.
+"""
+
+from cortexshift.tui.actions import TuiExitAction, TuiExitRequest
+from cortexshift.tui.app import CortexShiftApp, build_app
+from cortexshift.tui.coordinator import TuiCoordinator, TuiSession
+from cortexshift.tui.facade import TuiFacade
+from cortexshift.tui.screens import TuiSection
+
+__all__ = [
+    "CortexShiftApp",
+    "TuiCoordinator",
+    "TuiExitAction",
+    "TuiExitRequest",
+    "TuiFacade",
+    "TuiSection",
+    "TuiSession",
+    "build_app",
+]

cortexshift/tui/actions.py

@@ -0,0 +1,58 @@
+"""The structured boundary between the dashboard and native provider launch.
+
+CortexShift never embeds a provider's terminal UI. When the operator chooses to run,
+resume, or switch, the Textual application exits and *returns* a `TuiExitRequest`. Only
+after `App.run()` has returned — and Textual has restored the terminal — does the
+coordinator invoke `RunService`, `ResumeService`, or `SwitchService`, handing raw terminal
+ownership to the native provider process.
+
+This module deliberately depends on nothing from Textual so the contract can be
+constructed, asserted, and dispatched without a running application.
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class TuiExitAction(StrEnum):
+    """A provider action the dashboard defers to the terminal coordinator."""
+
+    RUN = "run"
+    RESUME = "resume"
+    SWITCH = "switch"
+
+
+@dataclass(frozen=True, slots=True)
+class TuiExitRequest:
+    """A request to launch a native provider after the dashboard has exited.
+
+    Constructing one launches nothing. It is a value returned out of the Textual
+    application, describing what the coordinator should do once the terminal is free.
+    """
+
+    action: TuiExitAction
+    provider: str
+    selected_session_id: str | None = None
+    force_new_session: bool = False
+    note: str | None = None
+
+    def __post_init__(self) -> None:
+        provider = self.provider.strip().lower()
+        if not provider:
+            raise ValueError("A provider identifier is required for a TUI exit request.")
+        object.__setattr__(self, "provider", provider)
+
+        if self.force_new_session and self.selected_session_id is not None:
+            raise ValueError("force_new_session and selected_session_id are mutually exclusive.")
+        if self.action is TuiExitAction.RUN and self.selected_session_id is not None:
+            raise ValueError("A run request never targets an existing session.")
+
+    @property
+    def description(self) -> str:
+        """Human-readable summary used in coordinator output and confirmations."""
+        verb = {
+            TuiExitAction.RUN: "Run",
+            TuiExitAction.RESUME: "Resume",
+            TuiExitAction.SWITCH: "Switch to",
+        }[self.action]
+        return f"{verb} {self.provider}"