cortexshift 0.1.0__py3-none-any.whl

cortexshift/__init__.py

@@ -0,0 +1,10 @@
+"""CortexShift: Switch agents. Keep the context.
+
+Provider-agnostic task handoff and state management for AI coding agents.
+"""
+
+from importlib.metadata import version
+from typing import Final
+
+__version__: Final[str] = version("cortexshift")
+__all__ = ["__version__"]

cortexshift/__main__.py

@@ -0,0 +1,6 @@
+"""Entrypoint for `python -m cortexshift`."""
+
+from cortexshift.cli.app import app
+
+if __name__ == "__main__":
+    app()

cortexshift/adapters/__init__.py

@@ -0,0 +1,22 @@
+from cortexshift.adapters.command_runner import SubprocessCommandRunner
+from cortexshift.adapters.discovery import BuiltinProviderDiscovery
+from cortexshift.adapters.git import GitRepositoryInspector
+from cortexshift.adapters.process_runner import SubprocessInteractiveProcessRunner
+from cortexshift.adapters.providers.antigravity import AntigravityRuntimeAdapter
+from cortexshift.adapters.providers.claude import ClaudeRuntimeAdapter
+from cortexshift.adapters.providers.codex import CodexRuntimeAdapter
+from cortexshift.adapters.sqlite import SQLiteStateStore
+from cortexshift.adapters.workspace_lease import FileWorkspaceLease, FileWorkspaceLeaseManager
+
+__all__ = [
+    "AntigravityRuntimeAdapter",
+    "BuiltinProviderDiscovery",
+    "ClaudeRuntimeAdapter",
+    "CodexRuntimeAdapter",
+    "FileWorkspaceLease",
+    "FileWorkspaceLeaseManager",
+    "GitRepositoryInspector",
+    "SQLiteStateStore",
+    "SubprocessCommandRunner",
+    "SubprocessInteractiveProcessRunner",
+]

cortexshift/adapters/command_runner.py

@@ -0,0 +1,116 @@
+"""Concrete subprocess command runner adapter."""
+
+import os
+import re
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+
+from cortexshift.ports.command_runner import CommandResult, CommandRunner
+
+_ANSI_ESCAPE_RE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+_MAX_OUTPUT_LENGTH = 10_000
+
+
+def _sanitize_output(text: str | bytes | None) -> str:
+    """Sanitize and bound subprocess output string."""
+    if text is None:
+        return ""
+    if isinstance(text, bytes):
+        text = text.decode("utf-8", errors="replace")
+    cleaned = _ANSI_ESCAPE_RE.sub("", text).strip()
+    if len(cleaned) > _MAX_OUTPUT_LENGTH:
+        return cleaned[:_MAX_OUTPUT_LENGTH] + "... [truncated]"
+    return cleaned
+
+
+class SubprocessCommandRunner(CommandRunner):
+    """Executes commands safely using standard library subprocess.
+
+    Invariants:
+    - Never uses shell=True.
+    - Commands must be supplied as a list of arguments.
+    - Always enforces a finite timeout.
+    - Catches OS and process errors without bubbling unhandled exceptions.
+    """
+
+    def __init__(self, default_timeout: float = 5.0) -> None:
+        self.default_timeout = default_timeout
+
+    def run(
+        self,
+        command: list[str],
+        timeout: float | None = None,
+        env: dict[str, str] | None = None,
+        cwd: Path | str | None = None,
+        sanitize: bool = True,
+    ) -> CommandResult:
+        if not command:
+            return CommandResult(
+                command=[],
+                exit_code=1,
+                stdout="",
+                stderr="Empty command provided",
+                error_message="Empty command provided",
+            )
+
+        eff_timeout = timeout if timeout is not None else self.default_timeout
+        eff_env: Mapping[str, str] | None = None
+        if env is not None:
+            eff_env = {**os.environ, **env}
+
+        cwd_path = str(cwd) if cwd is not None else None
+
+        try:
+            completed = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                timeout=eff_timeout,
+                shell=False,
+                env=eff_env,
+                cwd=cwd_path,
+                check=False,
+            )
+            stdout = _sanitize_output(completed.stdout) if sanitize else completed.stdout
+            stderr = _sanitize_output(completed.stderr) if sanitize else completed.stderr
+            return CommandResult(
+                command=command,
+                exit_code=completed.returncode,
+                stdout=stdout,
+                stderr=stderr,
+            )
+        except subprocess.TimeoutExpired:
+            return CommandResult(
+                command=command,
+                exit_code=-1,
+                stdout="",
+                stderr=f"Command timed out after {eff_timeout} seconds",
+                timed_out=True,
+                error_message=f"Command timed out after {eff_timeout} seconds",
+            )
+        except FileNotFoundError:
+            return CommandResult(
+                command=command,
+                exit_code=127,
+                stdout="",
+                stderr=f"Executable '{command[0]}' not found",
+                not_found=True,
+                error_message=f"Executable '{command[0]}' not found",
+            )
+        except PermissionError:
+            return CommandResult(
+                command=command,
+                exit_code=126,
+                stdout="",
+                stderr=f"Permission denied executing '{command[0]}'",
+                error_message=f"Permission denied executing '{command[0]}'",
+            )
+        except OSError as exc:
+            return CommandResult(
+                command=command,
+                exit_code=1,
+                stdout="",
+                stderr=str(exc),
+                error_message=str(exc),
+            )

cortexshift/adapters/discovery.py

@@ -0,0 +1,55 @@
+"""Built-in provider discovery adapter registering native agent probes."""
+
+import shutil
+from collections.abc import Callable
+
+from cortexshift.adapters.command_runner import SubprocessCommandRunner
+from cortexshift.adapters.providers.antigravity import AntigravityProviderProbe
+from cortexshift.adapters.providers.claude import ClaudeProviderProbe
+from cortexshift.adapters.providers.codex import CodexProviderProbe
+from cortexshift.domain.doctor import ProviderDiagnostic
+from cortexshift.domain.provider import (
+    PROVIDER_ANTIGRAVITY,
+    PROVIDER_CLAUDE,
+    PROVIDER_CODEX,
+    ProviderId,
+)
+from cortexshift.ports.command_runner import CommandRunner
+from cortexshift.ports.discovery import ProviderDiscoveryPort, ProviderProbe
+
+
+class BuiltinProviderDiscovery(ProviderDiscoveryPort):
+    """Discovery adapter registering and probing built-in coding agent providers.
+
+    Manages native probes for Claude Code, OpenAI Codex, and Google Antigravity.
+    """
+
+    def __init__(
+        self,
+        command_runner: CommandRunner | None = None,
+        which_fn: Callable[[str], str | None] = shutil.which,
+    ) -> None:
+        runner = command_runner or SubprocessCommandRunner()
+        self._probes: dict[ProviderId, ProviderProbe] = {
+            PROVIDER_CLAUDE: ClaudeProviderProbe(runner, which_fn=which_fn),
+            PROVIDER_CODEX: CodexProviderProbe(runner, which_fn=which_fn),
+            PROVIDER_ANTIGRAVITY: AntigravityProviderProbe(runner, which_fn=which_fn),
+        }
+
+    def get_supported_provider_ids(self) -> list[ProviderId]:
+        """Return the canonical IDs of all supported built-in providers."""
+        return list(self._probes.keys())
+
+    def discover_provider(self, provider_id: ProviderId) -> ProviderDiagnostic:
+        """Probe a specific provider by its ID.
+
+        Raises:
+            KeyError: If the provider is not registered.
+        """
+        if provider_id not in self._probes:
+            raise KeyError(f"Provider '{provider_id}' is not supported")
+        return self._probes[provider_id].probe()
+
+    def discover_all(self) -> list[ProviderDiagnostic]:
+        """Probe all registered providers in declaration order."""
+        return [probe.probe() for probe in self._probes.values()]

cortexshift/adapters/git/__init__.py

@@ -0,0 +1,10 @@
+"""Git adapter package for repository inspection."""
+
+from cortexshift.adapters.git.inspector import GitRepositoryInspector
+from cortexshift.adapters.git.parser import ParsedGitStatus, parse_porcelain_status
+
+__all__ = [
+    "GitRepositoryInspector",
+    "ParsedGitStatus",
+    "parse_porcelain_status",
+]

cortexshift/adapters/git/inspector.py

@@ -0,0 +1,321 @@
+"""Native Git repository inspector adapter."""
+
+import re
+import shutil
+from pathlib import Path
+
+from cortexshift.adapters.command_runner import SubprocessCommandRunner
+from cortexshift.adapters.git.parser import parse_porcelain_status
+from cortexshift.domain.git import (
+    GitSnapshot,
+    RepositoryInspection,
+    RepositoryInspectionStatus,
+)
+from cortexshift.domain.identifiers import generate_id, utc_now
+from cortexshift.ports.command_runner import CommandRunner
+from cortexshift.ports.repository import RepositoryInspector
+
+_GIT_ENV: dict[str, str] = {
+    "GIT_TERMINAL_PROMPT": "0",
+    "GIT_PAGER": "cat",
+    "GIT_OPTIONAL_LOCKS": "0",
+}
+
+_GIT_VERSION_RE = re.compile(r"git\s+version\s+([0-9]+(?:\.[0-9]+)*)")
+
+
+class GitRepositoryInspector(RepositoryInspector):
+    """Concrete repository inspector using the native local git CLI.
+
+    Invariants:
+    - Never modifies repository state (strictly read-only commands).
+    - Never uses shell=True.
+    - Bound by finite timeouts.
+    - Safe against NUL-delimited and unusual filenames.
+    - Accurately scopes status and diff summaries in monorepos.
+    - Distinguishes unborn repositories, detached HEADs, and non-git projects.
+    """
+
+    def __init__(
+        self,
+        command_runner: CommandRunner | None = None,
+        default_timeout: float = 10.0,
+    ) -> None:
+        self._runner = command_runner or SubprocessCommandRunner(default_timeout=default_timeout)
+        self.default_timeout = default_timeout
+
+    def _extract_git_version(self) -> str | None:
+        """Extract installed Git version string, or None if unavailable."""
+        res = self._runner.run(["git", "--version"], timeout=5.0)
+        if not res.success or not res.stdout:
+            return None
+        match = _GIT_VERSION_RE.search(res.stdout)
+        if match:
+            return match.group(1)
+        return res.stdout.strip()
+
+    def inspect(self, project_root: Path | str, project_id: str = "") -> RepositoryInspection:
+        """Perform a safe, read-only live inspection of the Git repository for a project root."""
+        resolved_root = Path(project_root).resolve()
+        root_str = str(resolved_root)
+
+        # 1. Verify git executable exists in PATH
+        if shutil.which("git") is None:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.GIT_NOT_INSTALLED,
+                project_root=root_str,
+                git_available=False,
+                diagnostic="Git executable was not found in PATH.",
+            )
+
+        git_version = self._extract_git_version()
+
+        # 2. Check if inside a Git working tree
+        tree_check = self._runner.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            cwd=resolved_root,
+            env=_GIT_ENV,
+            timeout=self.default_timeout,
+        )
+        if tree_check.timed_out:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git inspection timed out.",
+            )
+        if not tree_check.success or tree_check.stdout.strip() != "true":
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.NOT_GIT_REPOSITORY,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="This CortexShift project is not inside a Git repository.",
+            )
+
+        # 3. Detect Git repository root
+        toplevel_res = self._runner.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=resolved_root,
+            env=_GIT_ENV,
+            timeout=self.default_timeout,
+        )
+        if toplevel_res.timed_out:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git inspection timed out.",
+            )
+        if not toplevel_res.success or not toplevel_res.stdout.strip():
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git repository inspection failed.",
+            )
+        git_root = str(Path(toplevel_res.stdout.strip()).resolve())
+
+        # 4. Detect prefix relative to git root (for monorepo scoping)
+        prefix_res = self._runner.run(
+            ["git", "rev-parse", "--show-prefix"],
+            cwd=resolved_root,
+            env=_GIT_ENV,
+            timeout=self.default_timeout,
+        )
+        if prefix_res.timed_out:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git inspection timed out.",
+            )
+        project_prefix = prefix_res.stdout.strip() if prefix_res.success else ""
+
+        # 5. Detect branch & detached HEAD
+        branch_res = self._runner.run(
+            ["git", "branch", "--show-current"],
+            cwd=resolved_root,
+            env=_GIT_ENV,
+            timeout=self.default_timeout,
+        )
+        if branch_res.timed_out:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git inspection timed out.",
+            )
+
+        current_branch = branch_res.stdout.strip() if branch_res.success else ""
+        branch: str | None = None
+        detached_head = False
+
+        if current_branch:
+            branch = current_branch
+            detached_head = False
+        else:
+            # Fallback for unborn branches or detached HEAD
+            sym_res = self._runner.run(
+                ["git", "symbolic-ref", "--short", "HEAD"],
+                cwd=resolved_root,
+                env=_GIT_ENV,
+                timeout=self.default_timeout,
+            )
+            if sym_res.timed_out:
+                return RepositoryInspection(
+                    status=RepositoryInspectionStatus.PROBE_ERROR,
+                    project_root=root_str,
+                    git_available=True,
+                    git_version=git_version,
+                    diagnostic="Git inspection timed out.",
+                )
+            if sym_res.success and sym_res.stdout.strip():
+                branch = sym_res.stdout.strip()
+                detached_head = False
+            else:
+                branch = None
+                # Check if HEAD commit exists
+                head_verify = self._runner.run(
+                    ["git", "rev-parse", "--verify", "HEAD"],
+                    cwd=resolved_root,
+                    env=_GIT_ENV,
+                    timeout=self.default_timeout,
+                )
+                if head_verify.timed_out:
+                    return RepositoryInspection(
+                        status=RepositoryInspectionStatus.PROBE_ERROR,
+                        project_root=root_str,
+                        git_available=True,
+                        git_version=git_version,
+                        diagnostic="Git inspection timed out.",
+                    )
+                detached_head = head_verify.success
+
+        # 6. Detect HEAD commit SHA
+        head_sha: str | None = None
+        head_res = self._runner.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=resolved_root,
+            env=_GIT_ENV,
+            timeout=self.default_timeout,
+        )
+        if head_res.timed_out:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git inspection timed out.",
+            )
+        if head_res.success and head_res.stdout.strip():
+            head_sha = head_res.stdout.strip()
+
+        # 7. Status and changed files (NUL-delimited, scoped to project pathspec)
+        status_res = self._runner.run(
+            ["git", "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", "."],
+            cwd=resolved_root,
+            env=_GIT_ENV,
+            timeout=self.default_timeout,
+            sanitize=False,
+        )
+        if status_res.timed_out:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git inspection timed out.",
+            )
+        if not status_res.success:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git repository inspection failed.",
+            )
+
+        parsed_status = parse_porcelain_status(status_res.stdout, project_prefix=project_prefix)
+
+        # 8. Working tree diff shortstat
+        diff_wt_res = self._runner.run(
+            ["git", "diff", "--shortstat", "--", "."],
+            cwd=resolved_root,
+            env=_GIT_ENV,
+            timeout=self.default_timeout,
+        )
+        if diff_wt_res.timed_out:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git inspection timed out.",
+            )
+        wt_summary = (
+            diff_wt_res.stdout.strip()
+            if diff_wt_res.success and diff_wt_res.stdout.strip()
+            else None
+        )
+
+        # 9. Staged diff shortstat
+        diff_staged_res = self._runner.run(
+            ["git", "diff", "--cached", "--shortstat", "--", "."],
+            cwd=resolved_root,
+            env=_GIT_ENV,
+            timeout=self.default_timeout,
+        )
+        if diff_staged_res.timed_out:
+            return RepositoryInspection(
+                status=RepositoryInspectionStatus.PROBE_ERROR,
+                project_root=root_str,
+                git_available=True,
+                git_version=git_version,
+                diagnostic="Git inspection timed out.",
+            )
+        staged_summary = (
+            diff_staged_res.stdout.strip()
+            if diff_staged_res.success and diff_staged_res.stdout.strip()
+            else None
+        )
+
+        dirty = bool(
+            parsed_status.staged_files
+            or parsed_status.modified_files
+            or parsed_status.untracked_files
+            or parsed_status.conflicted_files
+        )
+
+        snapshot = GitSnapshot(
+            id=generate_id("snap"),
+            project_id=project_id or "proj_default",
+            project_root=root_str,
+            git_root=git_root,
+            git_version=git_version,
+            branch=branch,
+            head_sha=head_sha,
+            detached_head=detached_head,
+            dirty=dirty,
+            staged_files=parsed_status.staged_files,
+            modified_files=parsed_status.modified_files,
+            untracked_files=parsed_status.untracked_files,
+            conflicted_files=parsed_status.conflicted_files,
+            working_tree_diff_summary=wt_summary,
+            staged_diff_summary=staged_summary,
+            captured_at=utc_now(),
+            metadata={"renames": parsed_status.renames} if parsed_status.renames else {},
+        )
+
+        return RepositoryInspection(
+            status=RepositoryInspectionStatus.READY,
+            project_root=root_str,
+            git_available=True,
+            git_version=git_version,
+            snapshot=snapshot,
+        )

cortexshift/adapters/git/parser.py

@@ -0,0 +1,140 @@
+"""Parser for machine-readable Git porcelain status output."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ParsedGitStatus:
+    """Structured collections of changed files extracted from Git status."""
+
+    staged_files: list[str]
+    modified_files: list[str]
+    untracked_files: list[str]
+    conflicted_files: list[str]
+    renames: dict[str, str] = field(default_factory=dict)
+
+
+def parse_porcelain_status(raw_output: str, project_prefix: str = "") -> ParsedGitStatus:
+    """Parse NUL-delimited machine-readable output from `git status --porcelain=v1 -z`.
+
+    Handles:
+    - Unusual filenames containing spaces, tabs, newlines, and Unicode
+    - Renames and copies consuming two consecutive NUL-delimited records
+    - Scope normalization relative to project_prefix (monorepo support)
+    - Conflict/unmerged status detection (UU, AA, DD, *U, U*)
+    - Mixed index and working tree modifications (e.g., MM, AM, RM)
+    - Deterministic ordering of all file collections
+
+    Args:
+        raw_output: NUL-separated stdout from `git status --porcelain=v1 -z`.
+        project_prefix: Path prefix of the CortexShift project relative to git root.
+
+    Returns:
+        A populated ParsedGitStatus object with project-relative paths.
+    """
+    if not raw_output:
+        return ParsedGitStatus(
+            staged_files=[],
+            modified_files=[],
+            untracked_files=[],
+            conflicted_files=[],
+        )
+
+    # Normalize prefix (strip leading/trailing slashes)
+    clean_prefix = project_prefix.strip("/")
+    prefix_with_slash = f"{clean_prefix}/" if clean_prefix else ""
+
+    tokens = raw_output.split("\x00")
+    if tokens and tokens[-1] == "":
+        tokens.pop()
+
+    staged: list[str] = []
+    modified: list[str] = []
+    untracked: list[str] = []
+    conflicted: list[str] = []
+    renames: dict[str, str] = {}
+
+    i = 0
+    while i < len(tokens):
+        entry = tokens[i]
+        if not entry:
+            i += 1
+            continue
+
+        if len(entry) < 3:
+            i += 1
+            continue
+
+        x = entry[0]
+        y = entry[1]
+        path = entry[3:]
+
+        orig_path: str | None = None
+        if x in ("R", "C") or y in ("R", "C"):
+            i += 1
+            if i < len(tokens):
+                orig_path = tokens[i]
+
+        i += 1
+
+        # Check project scope: in monorepos, filter out files outside the project scope
+        if clean_prefix:
+            if not (path == clean_prefix or path.startswith(prefix_with_slash)):
+                # Outside project scope
+                continue
+            # Normalize path relative to project root
+            normalized_path = (
+                path[len(prefix_with_slash) :] if path.startswith(prefix_with_slash) else "."
+            )
+        else:
+            normalized_path = path
+
+        # Normalize orig_path if present
+        normalized_orig: str | None = None
+        if orig_path is not None:
+            if clean_prefix:
+                if orig_path.startswith(prefix_with_slash):
+                    normalized_orig = orig_path[len(prefix_with_slash) :]
+                else:
+                    normalized_orig = orig_path
+            else:
+                normalized_orig = orig_path
+
+        if normalized_orig is not None:
+            renames[normalized_path] = normalized_orig
+
+        # Exclude CortexShift private runtime state directory
+        if normalized_path == ".cortexshift" or normalized_path.startswith(".cortexshift/"):
+            continue
+
+        # 1. Untracked
+        if x == "?" and y == "?":
+            untracked.append(normalized_path)
+            continue
+
+        # 2. Ignored
+        if x == "!" and y == "!":
+            continue
+
+        # 3. Unmerged / Conflicted
+        # In Git porcelain, unmerged states: DD, AU, UD, UA, DU, AA, UU
+        is_unmerged = "U" in (x, y) or (x == "A" and y == "A") or (x == "D" and y == "D")
+        if is_unmerged:
+            conflicted.append(normalized_path)
+            continue
+
+        # 4. Staged modifications (index changes)
+        if x in ("M", "A", "D", "R", "C", "T"):
+            staged.append(normalized_path)
+
+        # 5. Unstaged modifications (working tree changes)
+        if y in ("M", "D", "T"):
+            modified.append(normalized_path)
+
+    return ParsedGitStatus(
+        staged_files=sorted(set(staged)),
+        modified_files=sorted(set(modified)),
+        untracked_files=sorted(set(untracked)),
+        conflicted_files=sorted(set(conflicted)),
+        renames=renames,
+    )