cortexshift 0.1.0__py3-none-any.whl

cortexshift/tui/screens/checkpoints.py

@@ -0,0 +1,188 @@
+"""The Checkpoints section: immutable historical observations.
+
+A checkpoint records what was true when it was captured. It is never presented as
+current truth, and a reported test summary is never presented as a verified result.
+"""
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.widgets import DataTable, Static
+
+from cortexshift.domain.checkpoint import CheckpointTestProvenance
+from cortexshift.tui.models import (
+    AUTHORITY_LABELS,
+    DataAuthority,
+    TuiCheckpointRow,
+    TuiStateSnapshot,
+    format_relative,
+    format_timestamp,
+)
+from cortexshift.tui.screens import SectionView, TuiSection
+from cortexshift.tui.widgets import (
+    BulletList,
+    EmptyState,
+    FieldList,
+    Panel,
+    current_row_key,
+    restore_cursor,
+)
+
+
+class CheckpointsSection(SectionView):
+    """Lists checkpoints newest first and renders the selected one in full."""
+
+    section = TuiSection.CHECKPOINTS
+
+    def __init__(self, id: str | None = None) -> None:
+        super().__init__(id=id)
+        self._rows: dict[str, TuiCheckpointRow] = {}
+
+    def compose(self) -> ComposeResult:
+        """Build the checkpoints layout."""
+        yield Static(Text("Checkpoints", style="bold"), classes="section-title")
+        yield EmptyState(
+            "No checkpoints yet.",
+            "Create one with:\n  c\n\nCheckpoints capture task and repository state "
+            "without holding the workspace lease.",
+            id="checkpoints-empty",
+        )
+        yield DataTable(id="checkpoints-table", cursor_type="row")
+
+        with Panel(
+            "Checkpoint detail",
+            authority=DataAuthority.HISTORICAL,
+            id="checkpoints-detail-panel",
+        ):
+            yield FieldList(id="checkpoints-detail")
+            yield Static(Text("Task snapshot", style="bold"), classes="panel-title")
+            yield FieldList(id="checkpoints-task")
+            yield Static(Text("Decisions", style="bold"), classes="panel-title")
+            yield BulletList(id="checkpoints-decisions")
+            yield Static(Text("Files touched", style="bold"), classes="panel-title")
+            yield BulletList(id="checkpoints-files")
+
+    def on_mount(self) -> None:
+        """Configure checkpoint table columns."""
+        table = self.query_one("#checkpoints-table", DataTable)
+        table.add_columns("Checkpoint", "Kind", "Session", "Created", "Git state")
+
+    def update_state(self, snapshot: TuiStateSnapshot) -> None:
+        """Refresh the checkpoints table, preserving the operator's selection."""
+        table = self.query_one("#checkpoints-table", DataTable)
+        empty = self.query_one("#checkpoints-empty", EmptyState)
+        detail_panel = self.query_one("#checkpoints-detail-panel", Panel)
+
+        rows = snapshot.checkpoints
+        self._rows = {row.id: row for row in rows}
+
+        empty.display = not rows
+        table.display = bool(rows)
+        detail_panel.display = bool(rows)
+
+        selected = current_row_key(table)
+        table.clear()
+        for row in rows:
+            session_label = row.session_id[:12] if row.session_id else "—"
+            table.add_row(
+                Text(row.short_id),
+                Text(row.kind),
+                Text(session_label),
+                Text(format_relative(row.created_at)),
+                Text(row.git_summary),
+                key=row.id,
+            )
+        restore_cursor(table, selected)
+        self._render_detail()
+
+    def on_data_table_row_highlighted(self, _event: DataTable.RowHighlighted) -> None:
+        """Render the highlighted checkpoint in full."""
+        self._render_detail()
+
+    def _render_detail(self) -> None:
+        key = current_row_key(self.query_one("#checkpoints-table", DataTable))
+        row = self._rows.get(key) if key else None
+
+        detail = self.query_one("#checkpoints-detail", FieldList)
+        task_fields = self.query_one("#checkpoints-task", FieldList)
+        decisions = self.query_one("#checkpoints-decisions", BulletList)
+        files = self.query_one("#checkpoints-files", BulletList)
+
+        if row is None:
+            detail.set_fields([])
+            task_fields.set_fields([])
+            decisions.set_items([])
+            files.set_items([])
+            return
+
+        payload = row.record.payload
+        test_status = payload.test_status
+        if not test_status.known:
+            test_line: str | Text = "No test result recorded."
+        elif test_status.provenance == CheckpointTestProvenance.VERIFIED:
+            test_line = Text(f"{test_status.summary}  (verified)", style="green")
+        else:
+            test_line = Text(
+                f"{test_status.summary}  (Reported / unverified)",
+                style="yellow",
+            )
+
+        git = payload.git_state
+        detail.set_fields(
+            [
+                ("Checkpoint ID", row.record.id),
+                ("Kind", row.record.kind.value),
+                ("Protocol", f"v{row.record.protocol_version}"),
+                ("Created at", format_timestamp(row.record.created_at)),
+                ("Session ID", row.record.session_id or "—"),
+                ("Git snapshot ID", row.record.git_snapshot_id or "—"),
+                ("Git state", f"{git.status.value} · {git.note}"),
+                ("Branch", git.branch or "—"),
+                ("HEAD", git.head_sha or "—"),
+                ("Dirty", "yes" if git.dirty else "no"),
+                (
+                    "Changed counts",
+                    f"staged {git.staged_count} · modified {git.modified_count} · "
+                    f"untracked {git.untracked_count} · conflicted {git.conflicted_count}",
+                ),
+                ("Test status", test_line),
+                ("Operator note", payload.operator_note or "—"),
+                ("Authority", AUTHORITY_LABELS[DataAuthority.HISTORICAL]),
+            ]
+        )
+
+        task = payload.task
+        task_fields.set_fields(
+            [
+                ("Task ID", task.task_id),
+                ("Title", task.task_title),
+                ("Status", task.task_status),
+                ("Current work", task.current_work or "—"),
+                (
+                    "Progress",
+                    f"{len(task.completed)} completed · {len(task.remaining)} remaining · "
+                    f"{len(task.known_issues)} issue(s)",
+                ),
+            ]
+        )
+
+        decisions.set_items(
+            list(payload.decisions),
+            empty="No decisions recorded in this checkpoint.",
+        )
+        files.set_items(
+            list(payload.files_touched),
+            limit=15,
+            empty="No files recorded as touched.",
+        )
+
+    @property
+    def selected_checkpoint(self) -> TuiCheckpointRow | None:
+        """The checkpoint row under the cursor, or None."""
+        key = current_row_key(self.query_one("#checkpoints-table", DataTable))
+        return self._rows.get(key) if key else None
+
+    def on_section_shown(self) -> None:
+        """Focus the table when there is anything to select."""
+        table = self.query_one("#checkpoints-table", DataTable)
+        if table.display:
+            table.focus()

cortexshift/tui/screens/handoffs.py

@@ -0,0 +1,180 @@
+"""The Handoffs section: canonical cross-provider handoff history.
+
+Rendered provider prompts are never persisted by CortexShift, so none are shown here.
+What is displayed is the canonical payload the handoff was derived from.
+"""
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.widgets import DataTable, Static
+
+from cortexshift.tui.models import (
+    AUTHORITY_LABELS,
+    DataAuthority,
+    TuiHandoffRow,
+    TuiStateSnapshot,
+    format_relative,
+    format_timestamp,
+)
+from cortexshift.tui.screens import SectionView, TuiSection
+from cortexshift.tui.widgets import (
+    BulletList,
+    EmptyState,
+    FieldList,
+    Panel,
+    current_row_key,
+    marked,
+    restore_cursor,
+)
+
+
+class HandoffsSection(SectionView):
+    """Lists handoffs newest first and renders the selected canonical payload."""
+
+    section = TuiSection.HANDOFFS
+
+    def __init__(self, id: str | None = None) -> None:
+        super().__init__(id=id)
+        self._rows: dict[str, TuiHandoffRow] = {}
+
+    def compose(self) -> ComposeResult:
+        """Build the handoffs layout."""
+        yield Static(Text("Handoffs", style="bold"), classes="section-title")
+        yield EmptyState(
+            "No handoffs yet.",
+            "Start with:\n  cortexshift run PROVIDER\n\n"
+            "Then press X to switch the task to another agent, or preview a handoff "
+            "without launching anything.",
+            id="handoffs-empty",
+        )
+        yield DataTable(id="handoffs-table", cursor_type="row")
+
+        with Panel(
+            "Handoff detail",
+            authority=DataAuthority.HISTORICAL,
+            id="handoffs-detail-panel",
+        ):
+            yield FieldList(id="handoffs-detail")
+            yield Static(Text("Completed", style="bold"), classes="panel-title")
+            yield BulletList(id="handoffs-completed")
+            yield Static(Text("Remaining", style="bold"), classes="panel-title")
+            yield BulletList(id="handoffs-remaining")
+            yield Static(Text("Files touched", style="bold"), classes="panel-title")
+            yield BulletList(id="handoffs-files")
+
+        yield Static(
+            Text(
+                "Press P to preview a fresh canonical handoff for a target provider. "
+                "Previews persist nothing and consume no model quota.",
+                style="dim italic",
+            ),
+        )
+
+    def on_mount(self) -> None:
+        """Configure handoff table columns."""
+        table = self.query_one("#handoffs-table", DataTable)
+        table.add_columns("Handoff", "From", "To", "Status", "Checkpoint", "Created")
+
+    def update_state(self, snapshot: TuiStateSnapshot) -> None:
+        """Refresh the handoffs table, preserving the operator's selection."""
+        table = self.query_one("#handoffs-table", DataTable)
+        empty = self.query_one("#handoffs-empty", EmptyState)
+        detail_panel = self.query_one("#handoffs-detail-panel", Panel)
+
+        rows = snapshot.handoffs
+        self._rows = {row.id: row for row in rows}
+
+        empty.display = not rows
+        table.display = bool(rows)
+        detail_panel.display = bool(rows)
+
+        selected = current_row_key(table)
+        table.clear()
+        for row in rows:
+            table.add_row(
+                Text(row.short_id),
+                Text(row.source_provider_id),
+                Text(row.target_provider_id),
+                marked(row.status, row.status),
+                Text(row.checkpoint_id[:12] if row.checkpoint_id else "—"),
+                Text(format_relative(row.created_at)),
+                key=row.id,
+            )
+        restore_cursor(table, selected)
+        self._render_detail()
+
+    def on_data_table_row_highlighted(self, _event: DataTable.RowHighlighted) -> None:
+        """Render the highlighted handoff in full."""
+        self._render_detail()
+
+    def _render_detail(self) -> None:
+        key = current_row_key(self.query_one("#handoffs-table", DataTable))
+        row = self._rows.get(key) if key else None
+
+        detail = self.query_one("#handoffs-detail", FieldList)
+        completed = self.query_one("#handoffs-completed", BulletList)
+        remaining = self.query_one("#handoffs-remaining", BulletList)
+        files = self.query_one("#handoffs-files", BulletList)
+
+        if row is None:
+            detail.set_fields([])
+            completed.set_items([])
+            remaining.set_items([])
+            files.set_items([])
+            return
+
+        record = row.record
+        payload = record.payload
+        git = payload.git_state
+        test_line = (
+            Text(f"{payload.test_status.summary}  (Reported / unverified)", style="yellow")
+            if payload.test_status.known
+            else Text(payload.test_status.summary)
+        )
+
+        detail.set_fields(
+            [
+                ("Handoff ID", record.id),
+                ("Protocol", f"v{record.protocol_version}"),
+                ("Task", f"{payload.task_title} ({record.task_id})"),
+                ("Source session", record.source_session_id),
+                ("Source provider", str(record.source_provider_id)),
+                ("Target session", record.target_session_id or "— (not launched)"),
+                ("Target provider", str(record.target_provider_id)),
+                ("Source checkpoint", record.source_checkpoint_id or "—"),
+                ("Git snapshot", record.git_snapshot_id or "—"),
+                ("Delivery status", record.status.value),
+                (
+                    "Failure",
+                    record.failure_code.value if record.failure_code else "—",
+                ),
+                ("Created at", format_timestamp(record.created_at)),
+                ("Delivered at", format_timestamp(record.delivered_at)),
+                ("Objective", payload.original_objective),
+                ("Current work", payload.current_work or "—"),
+                ("Test status", test_line),
+                (
+                    "Git state",
+                    f"{git.status.value} · {git.branch or '(detached)'} · "
+                    f"{'dirty' if git.dirty else 'clean'}",
+                ),
+                ("Next action", payload.recommended_next_action),
+                ("Authority", AUTHORITY_LABELS[DataAuthority.HISTORICAL]),
+            ]
+        )
+
+        completed.set_items(list(payload.completed), empty="Nothing recorded as completed.")
+        remaining.set_items(list(payload.remaining), empty="No remaining items recorded.")
+        files.set_items(list(payload.files_touched), limit=15, empty="No files recorded.")
+
+    @property
+    def selected_handoff(self) -> TuiHandoffRow | None:
+        """The handoff row under the cursor, or None."""
+        key = current_row_key(self.query_one("#handoffs-table", DataTable))
+        return self._rows.get(key) if key else None
+
+    def on_section_shown(self) -> None:
+        """Focus the table when there is anything to select."""
+        table = self.query_one("#handoffs-table", DataTable)
+        if table.display:
+            table.focus()

cortexshift/tui/screens/help.py

@@ -0,0 +1,117 @@
+"""The Help modal: the keyboard contract, in one place."""
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Button, Static
+
+HELP_SECTIONS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
+    (
+        "Navigation",
+        (
+            ("1", "Overview"),
+            ("2", "Task"),
+            ("3", "Repository"),
+            ("4", "Sessions"),
+            ("5", "Checkpoints"),
+            ("6", "Handoffs"),
+            ("7", "Providers"),
+            ("tab / shift+tab", "Move focus between widgets"),
+            ("↑ ↓ / page up / page down", "Move within tables and lists"),
+        ),
+    ),
+    (
+        "Refresh",
+        (
+            ("r", "Refresh everything, including live Git and provider discovery"),
+            ("", "Persisted state also refreshes on a lightweight timer (~2s)"),
+            ("", "Git runs on entry to Repository and on explicit refresh only"),
+        ),
+    ),
+    (
+        "Task",
+        (
+            ("w", "Set current work"),
+            ("m", "Mark a remaining item completed"),
+            ("n", "Add a remaining item"),
+            ("i", "Record a known issue"),
+            ("a / enter", "Activate the selected task (Task screen)"),
+        ),
+    ),
+    (
+        "Checkpoints & recovery",
+        (
+            ("c", "Create a MANUAL checkpoint (no workspace lease held)"),
+            ("shift+r", "Review and run crash recovery"),
+        ),
+    ),
+    (
+        "Providers",
+        (
+            ("x", "Provider action palette — run, resume, or switch"),
+            ("p", "Preview a canonical handoff (persists nothing, no model call)"),
+            ("g", "Configure workspace MCP for Antigravity"),
+        ),
+    ),
+    (
+        "General",
+        (
+            ("ctrl+p", "Command palette"),
+            ("?", "This help"),
+            ("q", "Quit"),
+        ),
+    ),
+)
+
+TERMINAL_NOTE = (
+    "Provider-native TUIs are never embedded. When you choose run, resume, or switch, "
+    "CortexShift closes this dashboard, restores the terminal, and only then launches "
+    "Claude Code, Codex, or Antigravity so the agent owns the terminal directly."
+)
+
+
+class HelpScreen(ModalScreen[None]):
+    """A concise reference for the dashboard's keyboard contract."""
+
+    BINDINGS = [
+        Binding("escape", "dismiss_help", "Close", show=True),
+        Binding("question_mark", "dismiss_help", "Close", show=False),
+        Binding("q", "dismiss_help", "Close", show=False),
+    ]
+
+    def compose(self) -> ComposeResult:
+        """Build the help modal."""
+        with Vertical(classes="modal", id="help-modal"):
+            yield Static(
+                Text("CortexShift — Keyboard Contract", style="bold"),
+                classes="modal-title",
+            )
+            with VerticalScroll(classes="modal-body"):
+                yield Static(self._render_body(), id="help-body")
+            yield Static(Text(TERMINAL_NOTE, style="dim italic"))
+            with Vertical(classes="modal-buttons"):
+                yield Button("Close", variant="primary", id="help-close")
+
+    @staticmethod
+    def _render_body() -> Text:
+        body = Text()
+        for index, (title, entries) in enumerate(HELP_SECTIONS):
+            if index:
+                body.append("\n\n")
+            body.append(title.upper(), style="bold cyan")
+            for key, description in entries:
+                body.append("\n")
+                body.append(f"  {key:<26}", style="bold")
+                body.append(description)
+        return body
+
+    def action_dismiss_help(self) -> None:
+        """Close the help modal."""
+        self.dismiss(None)
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Close on button activation."""
+        event.stop()
+        self.dismiss(None)

cortexshift/tui/screens/overview.py

@@ -0,0 +1,200 @@
+"""The Overview section: the default landing view of the control center."""
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Static
+
+from cortexshift.tui.models import (
+    DataAuthority,
+    TuiMcpStatus,
+    TuiProviderStatus,
+    TuiRepositoryModel,
+    TuiStateSnapshot,
+    WorkspaceActivity,
+    format_relative,
+    truncate,
+)
+from cortexshift.tui.screens import SectionView, TuiSection
+from cortexshift.tui.widgets import (
+    BulletList,
+    FieldList,
+    Panel,
+    marked,
+    render_progress_bar,
+)
+
+MARKER_WARN = "!"
+
+
+class OverviewSection(SectionView):
+    """Project identity, active task progress, repository state, and recent activity."""
+
+    section = TuiSection.OVERVIEW
+
+    def compose(self) -> ComposeResult:
+        """Build the overview layout."""
+        yield Static(Text("Overview", style="bold"), classes="section-title")
+        yield Static("", id="overview-recovery", classes="notice")
+
+        with Horizontal(classes="columns"):
+            with Vertical(classes="column"):
+                with Panel("Project"):
+                    yield FieldList(id="overview-project")
+                with Panel("Active task"):
+                    yield Static("", id="overview-task-title")
+                    yield Static("", id="overview-progress")
+                    yield FieldList(id="overview-task")
+            with Vertical(classes="column"):
+                with Panel("Repository", authority=DataAuthority.LIVE):
+                    yield FieldList(id="overview-repository")
+                with Panel("Activity"):
+                    yield FieldList(id="overview-activity")
+                with Panel("Providers"):
+                    yield BulletList(id="overview-providers")
+
+    # -- rendering ---------------------------------------------------------
+
+    def update_state(self, snapshot: TuiStateSnapshot) -> None:
+        """Render project, task, and activity facts from persisted state."""
+        project = snapshot.project
+        self.query_one("#overview-project", FieldList).set_fields(
+            [
+                ("Project", project.name),
+                ("Project ID", project.short_id),
+                ("CortexShift", project.cortexshift_version),
+                ("Schema", f"v{project.schema_version}"),
+            ]
+        )
+
+        self._render_task(snapshot)
+        self._render_activity(snapshot)
+
+    def _render_task(self, snapshot: TuiStateSnapshot) -> None:
+        title = self.query_one("#overview-task-title", Static)
+        progress = self.query_one("#overview-progress", Static)
+        fields = self.query_one("#overview-task", FieldList)
+
+        task = snapshot.active_task
+        if task is None:
+            title.update(Text("No active task.", style="bold"))
+            progress.update(
+                Text(
+                    "Activate a task on the Task screen (2), or create one first.",
+                    style="dim",
+                )
+            )
+            fields.set_fields([])
+            return
+
+        heading = Text()
+        heading.append(task.title, style="bold")
+        heading.append(f"   {task.status}", style="dim")
+        title.update(heading)
+        progress.update(render_progress_bar(task.progress))
+        fields.set_fields(
+            [
+                ("Task ID", task.short_id),
+                ("Objective", truncate(task.objective, 70)),
+                ("Current work", truncate(task.current_work, 70)),
+                ("Completed", str(task.progress.completed_count)),
+                ("Remaining", str(task.progress.remaining_count)),
+                ("Known issues", str(task.progress.issue_count)),
+            ]
+        )
+
+    def _render_activity(self, snapshot: TuiStateSnapshot) -> None:
+        activity = snapshot.activity
+        session = activity.latest_session
+        checkpoint = activity.latest_checkpoint
+        handoff = activity.latest_handoff
+
+        session_value: str | Text = "No session recorded."
+        if session is not None:
+            session_value = Text()
+            session_value.append(f"{session.provider_id} · ")
+            session_value.append_text(marked(session.status, session.status))
+            session_value.append(f" · {format_relative(session.started_at)}")
+
+        checkpoint_value: str | Text = "No checkpoint recorded."
+        if checkpoint is not None:
+            checkpoint_value = f"{checkpoint.kind} · {format_relative(checkpoint.created_at)}"
+
+        handoff_value: str | Text = "No handoff recorded."
+        if handoff is not None:
+            handoff_value = (
+                f"{handoff.source_provider_id} → {handoff.target_provider_id} · "
+                f"{handoff.status} · {format_relative(handoff.created_at)}"
+            )
+
+        self.query_one("#overview-activity", FieldList).set_fields(
+            [
+                ("Latest session", session_value),
+                ("Latest checkpoint", checkpoint_value),
+                ("Latest handoff", handoff_value),
+            ]
+        )
+
+        notice = self.query_one("#overview-recovery", Static)
+        if activity.recovery_may_be_required:
+            count = activity.unfinalized_session_count
+            plural = "" if count == 1 else "s"
+            notice.update(
+                Text(
+                    f"{MARKER_WARN} {count} unfinalized CortexShift Session{plural} recorded. "
+                    "Recovery may be required — press R to review.",
+                    style="bold yellow",
+                )
+            )
+        else:
+            notice.update("")
+
+    def update_repository(self, repository: TuiRepositoryModel | None) -> None:
+        """Render the most recent live Git observation."""
+        fields = self.query_one("#overview-repository", FieldList)
+        if repository is None:
+            fields.set_fields([("Git", Text("Inspecting…", style="dim italic"))])
+            return
+
+        if not repository.ready:
+            fields.set_fields(
+                [
+                    ("Git", marked("warn", repository.status.value)),
+                    ("Detail", truncate(repository.diagnostic, 60)),
+                ]
+            )
+            return
+
+        branch = repository.branch or "(detached HEAD)"
+        state = "dirty" if repository.dirty else "clean"
+        fields.set_fields(
+            [
+                ("Branch", branch),
+                ("HEAD", repository.short_head),
+                ("State", marked(state, state)),
+                ("Changed files", str(repository.changed_file_count)),
+                ("Observed", format_relative(repository.observed_at)),
+            ]
+        )
+
+    def update_providers(
+        self,
+        providers: tuple[TuiProviderStatus, ...],
+        mcp: TuiMcpStatus | None,
+    ) -> None:
+        """Render a compact provider availability list without account details."""
+        widget = self.query_one("#overview-providers", BulletList)
+        if not providers:
+            widget.set_items([], empty="Probing providers…")
+            return
+
+        lines = [
+            f"{provider.display_name:<14}{'available' if provider.available else 'unavailable'}"
+            for provider in providers
+        ]
+        if mcp is not None and not mcp.antigravity_configured:
+            lines.append("Antigravity workspace MCP is not configured (Providers · G)")
+        widget.set_items(lines, limit=10)
+
+    def update_activity(self, activity: WorkspaceActivity) -> None:
+        """Workspace lease state is surfaced by the app's status line."""