cortexshift 0.1.0__py3-none-any.whl

cortexshift/adapters/workspace_lease.py

@@ -0,0 +1,123 @@
+"""File-based OS advisory lock implementation of the WorkspaceLease port."""
+
+import os
+import sys
+from pathlib import Path
+
+from cortexshift.ports.workspace_lease import WorkspaceLease, WorkspaceLeaseManager
+
+STATE_DIR_NAME = ".cortexshift"
+LOCK_FILE_NAME = "agent.lock"
+
+
+class FileWorkspaceLease(WorkspaceLease):
+    """OS-level advisory file lock enforcing single-mutating-agent invariant per project."""
+
+    def __init__(self, lock_path: Path) -> None:
+        self._lock_path = Path(lock_path).resolve()
+        self._fd: int | None = None
+
+    @property
+    def lock_path(self) -> Path:
+        return self._lock_path
+
+    def acquire(self) -> bool:
+        """Attempt non-blocking exclusive acquisition of the workspace lock."""
+        if self._fd is not None:
+            return True
+
+        self._lock_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            fd = os.open(str(self._lock_path), os.O_RDWR | os.O_CREAT, 0o600)
+        except OSError:
+            return False
+
+        try:
+            if sys.platform == "win32":
+                import msvcrt
+
+                if os.path.getsize(str(self._lock_path)) == 0:
+                    os.write(fd, b"\0")
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+            self._fd = fd
+            return True
+        except (BlockingIOError, OSError):
+            os.close(fd)
+            return False
+
+    def release(self) -> None:
+        """Release the exclusive lock and close the underlying file descriptor."""
+        if self._fd is None:
+            return
+
+        try:
+            if sys.platform == "win32":
+                import msvcrt
+
+                os.lseek(self._fd, 0, os.SEEK_SET)
+                msvcrt.locking(self._fd, msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(self._fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        finally:
+            os.close(self._fd)
+            self._fd = None
+
+    def is_locked(self) -> bool:
+        """Check whether the lock is currently held by any process."""
+        if self._fd is not None:
+            return True
+        if not self._lock_path.exists():
+            return False
+        try:
+            fd = os.open(str(self._lock_path), os.O_RDWR, 0o600)
+        except OSError:
+            return False
+
+        try:
+            if sys.platform == "win32":
+                import msvcrt
+
+                if os.path.getsize(str(self._lock_path)) == 0:
+                    return False
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            return False
+        except (BlockingIOError, OSError):
+            return True
+        finally:
+            os.close(fd)
+
+    def __enter__(self) -> "FileWorkspaceLease":
+        if not self.acquire():
+            from cortexshift.domain.errors import WorkspaceLockedError
+
+            raise WorkspaceLockedError(lock_path=self._lock_path)
+        return self
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
+        self.release()
+
+
+class FileWorkspaceLeaseManager(WorkspaceLeaseManager):
+    """Standard file-backed workspace lease manager."""
+
+    def get_lease(self, project_root: Path) -> WorkspaceLease:
+        lock_path = project_root / STATE_DIR_NAME / LOCK_FILE_NAME
+        return FileWorkspaceLease(lock_path)

cortexshift/application/__init__.py

@@ -0,0 +1,42 @@
+"""Application layer for CortexShift use cases and workflows.
+
+Orchestrates domain entities, ports, and lifecycle policies.
+"""
+
+from cortexshift.application.checkpoint_builder import CheckpointBuilder
+from cortexshift.application.checkpoint_service import CheckpointService
+from cortexshift.application.doctor import DoctorService, UnknownProviderError
+from cortexshift.application.init_service import (
+    ProjectInitializationService,
+    ProjectInitResult,
+)
+from cortexshift.application.locator import ProjectLocator
+from cortexshift.application.recovery_service import RecoveryReport, RecoveryService
+from cortexshift.application.repository_service import RepositoryService
+from cortexshift.application.run_service import (
+    DryRunResult,
+    ProviderRuntimeRegistry,
+    RunService,
+)
+from cortexshift.application.session_service import SessionService
+from cortexshift.application.status_service import ProjectStatusService
+from cortexshift.application.task_service import TaskService
+
+__all__ = [
+    "CheckpointBuilder",
+    "CheckpointService",
+    "DoctorService",
+    "DryRunResult",
+    "ProjectInitializationService",
+    "ProjectInitResult",
+    "ProjectLocator",
+    "ProjectStatusService",
+    "ProviderRuntimeRegistry",
+    "RecoveryReport",
+    "RecoveryService",
+    "RepositoryService",
+    "RunService",
+    "SessionService",
+    "TaskService",
+    "UnknownProviderError",
+]

cortexshift/application/checkpoint_builder.py

@@ -0,0 +1,218 @@
+"""Deterministic construction of canonical checkpoint records and payloads.
+
+The builder is pure: it performs no I/O, invokes no provider, and consumes no model
+quota. Its inputs are canonical Project, canonical Task, live repository inspection,
+optional Session metadata, and optional enrichment (decisions, test summary, note).
+"""
+
+from typing import Any
+
+from cortexshift.application.handoff_builder import derive_files_touched
+from cortexshift.domain.checkpoint import (
+    CHECKPOINT_PROTOCOL_VERSION,
+    MAX_DECISION_CHARS,
+    MAX_OPERATOR_NOTE_CHARS,
+    MAX_TEST_SUMMARY_CHARS,
+    CheckpointGitState,
+    CheckpointKind,
+    CheckpointPayload,
+    CheckpointRecord,
+    CheckpointSourceSession,
+    CheckpointTaskSnapshot,
+    CheckpointTestProvenance,
+    CheckpointTestStatus,
+    generate_checkpoint_id,
+)
+from cortexshift.domain.errors import InvalidCheckpointInputError
+from cortexshift.domain.git import RepositoryInspection, RepositoryInspectionStatus
+from cortexshift.domain.identifiers import utc_now
+from cortexshift.domain.project import Project
+from cortexshift.domain.session import Session
+from cortexshift.domain.task import Task, TaskStatus
+
+_GIT_NOTE_READY = (
+    "Live Git inspection succeeded at checkpoint time. "
+    "This is a historical observation, not current truth; re-check with `git status`."
+)
+_GIT_NOTE_NOT_INSTALLED = (
+    "Git was not found on this machine at checkpoint time. No repository state could be observed."
+)
+_GIT_NOTE_NOT_REPOSITORY = (
+    "This CortexShift project is not inside a Git repository. "
+    "No repository state could be observed."
+)
+_GIT_NOTE_PROBE_ERROR = (
+    "Git repository inspection failed at checkpoint time. "
+    "Treat any repository claim below as unverified and inspect the workspace directly."
+)
+
+_GIT_NOTES: dict[RepositoryInspectionStatus, str] = {
+    RepositoryInspectionStatus.READY: _GIT_NOTE_READY,
+    RepositoryInspectionStatus.GIT_NOT_INSTALLED: _GIT_NOTE_NOT_INSTALLED,
+    RepositoryInspectionStatus.NOT_GIT_REPOSITORY: _GIT_NOTE_NOT_REPOSITORY,
+    RepositoryInspectionStatus.PROBE_ERROR: _GIT_NOTE_PROBE_ERROR,
+}
+
+
+def build_checkpoint_git_state(
+    inspection: RepositoryInspection,
+    snapshot_id: str | None = None,
+) -> CheckpointGitState:
+    """Build the checkpoint GIT STATE section honestly encoding unavailable Git."""
+    note = _GIT_NOTES.get(inspection.status, _GIT_NOTE_PROBE_ERROR)
+    snapshot = inspection.snapshot
+
+    if inspection.status != RepositoryInspectionStatus.READY or snapshot is None:
+        return CheckpointGitState(status=inspection.status, available=False, note=note)
+
+    return CheckpointGitState(
+        status=inspection.status,
+        available=True,
+        note=note,
+        branch=snapshot.branch,
+        head_sha=snapshot.head_sha,
+        detached_head=snapshot.detached_head,
+        dirty=snapshot.dirty,
+        staged_count=len(snapshot.staged_files),
+        modified_count=len(snapshot.modified_files),
+        untracked_count=len(snapshot.untracked_files),
+        conflicted_count=len(snapshot.conflicted_files),
+        working_tree_diff_summary=snapshot.working_tree_diff_summary,
+        staged_diff_summary=snapshot.staged_diff_summary,
+        snapshot_id=snapshot_id,
+    )
+
+
+class CheckpointBuilder:
+    """Constructs canonical CheckpointRecord and CheckpointPayload entities deterministically."""
+
+    @classmethod
+    def build(
+        cls,
+        project: Project,
+        task: Task,
+        inspection: RepositoryInspection,
+        kind: CheckpointKind,
+        snapshot_id: str | None = None,
+        session: Session | None = None,
+        decisions: list[str] | None = None,
+        test_summary: str | None = None,
+        test_provenance: CheckpointTestProvenance = CheckpointTestProvenance.UNKNOWN,
+        operator_note: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> CheckpointRecord:
+        """Build a canonical CheckpointRecord from durable inputs.
+
+        Raises:
+            InvalidCheckpointInputError: If note, decisions, or test summary exceed bounds.
+        """
+        # Validate inputs
+        cleaned_note: str | None = None
+        if operator_note is not None:
+            cleaned_note = operator_note.strip()
+            if len(cleaned_note) > MAX_OPERATOR_NOTE_CHARS:
+                raise InvalidCheckpointInputError(
+                    f"Operator note exceeds maximum allowed length of "
+                    f"{MAX_OPERATOR_NOTE_CHARS} characters."
+                )
+            if not cleaned_note:
+                cleaned_note = None
+
+        cleaned_decisions: list[str] = []
+        if decisions is not None:
+            for decision in decisions:
+                d = decision.strip()
+                if d:
+                    if len(d) > MAX_DECISION_CHARS:
+                        raise InvalidCheckpointInputError(
+                            f"Decision entry exceeds maximum allowed length of "
+                            f"{MAX_DECISION_CHARS} characters."
+                        )
+                    cleaned_decisions.append(d)
+
+        cleaned_test_summary: str | None = None
+        if test_summary is not None:
+            cleaned_test_summary = test_summary.strip()
+            if len(cleaned_test_summary) > MAX_TEST_SUMMARY_CHARS:
+                raise InvalidCheckpointInputError(
+                    f"Test summary exceeds maximum allowed length of "
+                    f"{MAX_TEST_SUMMARY_CHARS} characters."
+                )
+            if not cleaned_test_summary:
+                cleaned_test_summary = None
+
+        # Build test status
+        if cleaned_test_summary is not None:
+            provenance = (
+                test_provenance
+                if test_provenance != CheckpointTestProvenance.UNKNOWN
+                else CheckpointTestProvenance.REPORTED
+            )
+            test_status = CheckpointTestStatus(
+                known=True,
+                summary=cleaned_test_summary,
+                provenance=provenance,
+            )
+        else:
+            test_status = CheckpointTestStatus(
+                known=False,
+                summary="No independently verified test results recorded.",
+                provenance=CheckpointTestProvenance.UNKNOWN,
+            )
+
+        # Build task snapshot
+        status_val = task.status.value if isinstance(task.status, TaskStatus) else str(task.status)
+        task_snapshot = CheckpointTaskSnapshot(
+            task_id=task.id,
+            task_title=task.title,
+            task_status=status_val,
+            objective=task.objective,
+            requirements=list(task.requirements),
+            constraints=list(task.constraints),
+            completed=list(task.completed_items),
+            current_work=task.current_work,
+            remaining=list(task.remaining_items),
+            known_issues=list(task.known_issues),
+        )
+
+        # Build source session summary
+        source_session_summary: CheckpointSourceSession | None = None
+        if session is not None:
+            source_session_summary = CheckpointSourceSession(
+                session_id=session.id,
+                provider_id=session.provider_id,
+                native_session_id=session.native_session_id,
+                status=session.status,
+                exit_reason=session.exit_reason,
+                exit_code=session.exit_code,
+            )
+
+        # Build Git state & files touched
+        git_state = build_checkpoint_git_state(inspection, snapshot_id=snapshot_id)
+        files_touched = derive_files_touched(inspection)
+
+        payload = CheckpointPayload(
+            protocol_version=CHECKPOINT_PROTOCOL_VERSION,
+            generated_at=utc_now(),
+            task=task_snapshot,
+            git_state=git_state,
+            files_touched=files_touched,
+            decisions=cleaned_decisions,
+            test_status=test_status,
+            operator_note=cleaned_note,
+            source_session=source_session_summary,
+            metadata=dict(metadata or {}),
+        )
+
+        return CheckpointRecord(
+            id=generate_checkpoint_id(),
+            protocol_version=CHECKPOINT_PROTOCOL_VERSION,
+            project_id=project.id,
+            task_id=task.id,
+            session_id=session.id if session else None,
+            git_snapshot_id=snapshot_id,
+            kind=kind,
+            payload=payload,
+            created_at=utc_now(),
+            metadata=dict(metadata or {}),
+        )

cortexshift/application/checkpoint_service.py

@@ -0,0 +1,273 @@
+"""Application service managing checkpoint creation, querying, and automatic session-end capture."""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from cortexshift.adapters.git.inspector import GitRepositoryInspector
+from cortexshift.adapters.sqlite.store import SQLiteStateStore
+from cortexshift.application.checkpoint_builder import CheckpointBuilder
+from cortexshift.application.locator import ProjectLocator
+from cortexshift.domain.checkpoint import (
+    CheckpointKind,
+    CheckpointRecord,
+    CheckpointTestProvenance,
+)
+from cortexshift.domain.errors import (
+    CheckpointNotFoundError,
+    GitProbeError,
+    NoActiveTaskError,
+    ProjectNotInitializedError,
+    SessionNotFoundError,
+    SessionTaskMismatchError,
+)
+from cortexshift.domain.git import RepositoryInspectionStatus
+from cortexshift.domain.project import Project
+from cortexshift.domain.session import Session, SessionExitReason
+from cortexshift.domain.task import Task
+from cortexshift.ports.repository import RepositoryInspector
+
+logger = logging.getLogger(__name__)
+
+
+class CheckpointService:
+    """Coordinates checkpoint operations across Project, Task, Repository, and Store."""
+
+    def __init__(
+        self,
+        inspector: RepositoryInspector | None = None,
+    ) -> None:
+        self._inspector = inspector or GitRepositoryInspector()
+
+    def _resolve_context(
+        self,
+        start_dir: Path | str | None = None,
+    ) -> tuple[Path, Project, Task, SQLiteStateStore]:
+        """Resolve project, active task, and state store."""
+        start_path = Path(start_dir) if start_dir is not None else None
+        project_root = ProjectLocator.find_project_root(start_path)
+        if project_root is None:
+            raise ProjectNotInitializedError()
+
+        db_path = ProjectLocator.get_database_path(project_root)
+        store = SQLiteStateStore(db_path, auto_migrate=False)
+
+        try:
+            project = store.get_default_project()
+            if project is None:
+                raise ProjectNotInitializedError()
+
+            active_task_id = store.get_active_task_id(project.id)
+            if not active_task_id:
+                raise NoActiveTaskError()
+
+            task = store.get_task(active_task_id)
+            if task is None:
+                raise NoActiveTaskError()
+
+            return project_root, project, task, store
+        except Exception:
+            store.close()
+            raise
+
+    def create_checkpoint(
+        self,
+        kind: CheckpointKind = CheckpointKind.MANUAL,
+        session_id: str | None = None,
+        decisions: list[str] | None = None,
+        test_summary: str | None = None,
+        test_provenance: CheckpointTestProvenance = CheckpointTestProvenance.REPORTED,
+        note: str | None = None,
+        start_dir: Path | str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> CheckpointRecord:
+        """Create and persist a canonical Checkpoint without requiring the workspace lease.
+
+        Manual checkpoints may be called from within a running provider session.
+        Inspection is non-atomic and advisory.
+        """
+        project_root, project, task, store = self._resolve_context(start_dir)
+        try:
+            # 1. Resolve session if requested or find latest for active task
+            session: Session | None = None
+            if session_id is not None:
+                session = store.get_session(session_id)
+                if session is None:
+                    raise SessionNotFoundError(session_id)
+                if session.task_id != task.id:
+                    raise SessionTaskMismatchError(session_id, task.id)
+            else:
+                sessions = store.list_sessions(task_id=task.id, limit=10)
+                # Prefer running or finished sessions over spawn-failed
+                for candidate in sessions:
+                    if candidate.exit_reason != SessionExitReason.SPAWN_FAILED:
+                        session = candidate
+                        break
+                if session is None and sessions:
+                    session = sessions[0]
+
+            # 2. Live Git inspection
+            inspection = self._inspector.inspect(
+                project_root=Path(project.repo_path),
+                project_id=project.id,
+            )
+
+            if inspection.status == RepositoryInspectionStatus.PROBE_ERROR:
+                raise GitProbeError(
+                    inspection.diagnostic
+                    or "Git repository inspection failed; refusing to create a checkpoint "
+                    "from an unreliable repository observation."
+                )
+
+            snapshot_id: str | None = None
+            if (
+                inspection.status == RepositoryInspectionStatus.READY
+                and inspection.snapshot is not None
+            ):
+                store.save_snapshot(inspection.snapshot)
+                snapshot_id = inspection.snapshot.id
+
+            # 3. Build immutable checkpoint record
+            record = CheckpointBuilder.build(
+                project=project,
+                task=task,
+                inspection=inspection,
+                kind=kind,
+                snapshot_id=snapshot_id,
+                session=session,
+                decisions=decisions,
+                test_summary=test_summary,
+                test_provenance=test_provenance,
+                operator_note=note,
+                metadata=metadata,
+            )
+
+            # 4. Persist
+            store.save_checkpoint(record)
+            return record
+        finally:
+            store.close()
+
+    def get_checkpoint(
+        self,
+        checkpoint_id: str,
+        start_dir: Path | str | None = None,
+    ) -> CheckpointRecord:
+        """Retrieve a Checkpoint by its unique identifier."""
+        start_path = Path(start_dir) if start_dir is not None else None
+        project_root = ProjectLocator.find_project_root(start_path)
+        if project_root is None:
+            raise ProjectNotInitializedError()
+
+        db_path = ProjectLocator.get_database_path(project_root)
+        with SQLiteStateStore(db_path, auto_migrate=False) as store:
+            checkpoint = store.get_checkpoint(checkpoint_id)
+            if checkpoint is None:
+                raise CheckpointNotFoundError(checkpoint_id)
+            return checkpoint
+
+    def list_checkpoints(
+        self,
+        task_id: str | None = None,
+        limit: int | None = 20,
+        start_dir: Path | str | None = None,
+    ) -> list[CheckpointRecord]:
+        """List checkpoints for the active task or project, newest first."""
+        start_path = Path(start_dir) if start_dir is not None else None
+        project_root = ProjectLocator.find_project_root(start_path)
+        if project_root is None:
+            raise ProjectNotInitializedError()
+
+        db_path = ProjectLocator.get_database_path(project_root)
+        with SQLiteStateStore(db_path, auto_migrate=False) as store:
+            project = store.get_default_project()
+            if project is None:
+                raise ProjectNotInitializedError()
+
+            resolved_task_id = task_id
+            if resolved_task_id is None:
+                resolved_task_id = store.get_active_task_id(project.id)
+
+            return store.list_checkpoints(
+                project_id=project.id,
+                task_id=resolved_task_id,
+                limit=limit,
+            )
+
+    def get_latest_checkpoint(
+        self,
+        task_id: str | None = None,
+        start_dir: Path | str | None = None,
+    ) -> CheckpointRecord | None:
+        """Retrieve the newest checkpoint for the active task."""
+        results = self.list_checkpoints(task_id=task_id, limit=1, start_dir=start_dir)
+        return results[0] if results else None
+
+    def capture_session_end_checkpoint(
+        self,
+        session: Session,
+        store: SQLiteStateStore,
+    ) -> CheckpointRecord | None:
+        """Safely capture an automatic SESSION_END checkpoint when a provider process finishes.
+
+        This method never raises an exception out to the caller, preventing checkpoint
+        failures from rewriting or failing an otherwise completed coding session.
+        """
+        try:
+            task = store.get_task(session.task_id)
+            if task is None:
+                return None
+
+            project = store.get_project(task.project_id)
+            if project is None:
+                return None
+
+            inspection = self._inspector.inspect(
+                project_root=Path(project.repo_path),
+                project_id=project.id,
+            )
+
+            if inspection.status == RepositoryInspectionStatus.PROBE_ERROR:
+                # Safe warning: record capture warning in session metadata without rewriting status
+                logger.warning(
+                    "Session-end checkpoint capture skipped: git probe error for session %s",
+                    session.id,
+                )
+                updated_meta = dict(session.metadata)
+                updated_meta["checkpoint_capture_warning"] = "git_probe_error"
+                store.save_session(session.model_copy(update={"metadata": updated_meta}))
+                return None
+
+            snapshot_id: str | None = None
+            if (
+                inspection.status == RepositoryInspectionStatus.READY
+                and inspection.snapshot is not None
+            ):
+                store.save_snapshot(inspection.snapshot)
+                snapshot_id = inspection.snapshot.id
+
+            record = CheckpointBuilder.build(
+                project=project,
+                task=task,
+                inspection=inspection,
+                kind=CheckpointKind.SESSION_END,
+                snapshot_id=snapshot_id,
+                session=session,
+                test_provenance=CheckpointTestProvenance.UNKNOWN,
+            )
+
+            store.save_checkpoint(record)
+            return record
+        except Exception as exc:
+            logger.warning(
+                "Failed to capture session-end checkpoint for session %s: %s",
+                session.id,
+                exc,
+            )
+            try:
+                updated_meta = dict(session.metadata)
+                updated_meta["checkpoint_capture_warning"] = str(exc)
+                store.save_session(session.model_copy(update={"metadata": updated_meta}))
+            except Exception:
+                pass
+            return None