pivot-tui 0.1.0__py3-none-any.whl

pivot_tui/AGENTS.md

@@ -0,0 +1,20 @@
+# Pivot TUI - Development Guidelines
+
+Pure RPC client over the engine's JSON-RPC 2.0 Unix socket.
+
+## Boundary Rules
+
+- **No direct state access.** Must not read lock files, cache files, or state files. All state goes through engine RPC.
+- **Import boundary:** May import `pivot.types` (pure type definitions). Must not import runtime modules (`engine`, `storage`, `config`).
+
+## Lifecycle
+
+One-shot and watch mode are source-configuration differences, not different lifecycles. The TUI should outlive run completion.
+
+## Event Stream
+
+Engine emits explanation events in the event stream. The TUI reconstructs history client-side from this stream.
+
+## Testing
+
+Use `FakeRpcServer` (`testing/fake_server.py`) for TUI tests — test against client interface contracts, not engine internals.

pivot_tui/__init__.py

@@ -0,0 +1,5 @@
+"""Textual-based TUI for the Pivot pipeline framework."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

pivot_tui/client.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+# pyright: reportMissingImports=false
+# pyright: reportUnknownVariableType=false
+# pyright: reportUnknownParameterType=false
+from typing import TYPE_CHECKING, Literal, Protocol, TypedDict
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from pivot.types import StageExplanation
+
+
+class EngineStatus(TypedDict):
+    state: Literal["idle", "active"]
+    running: list[str]
+    pending: list[str]
+
+
+class CommitResult(TypedDict):
+    committed: list[str]
+    failed: list[str]
+
+
+class StageInfoResult(TypedDict):
+    name: str
+    deps: list[str]
+    outs: list[str]
+
+
+class VersionedEvent(TypedDict):
+    version: int
+    event: dict[str, object]
+
+
+class EventBatch(TypedDict):
+    version: int
+    events: list[VersionedEvent]
+
+
+class PivotRpc(Protocol):
+    """RPC methods for engine interaction (no transport concern)."""
+
+    async def run(self, stages: list[str] | None = None, *, force: bool = False) -> bool: ...
+
+    async def cancel(self) -> bool: ...
+
+    async def commit(self) -> CommitResult: ...
+
+    async def status(self) -> EngineStatus: ...
+
+    async def stages(self) -> list[str]: ...
+
+    async def stage_info(self, stage: str) -> StageInfoResult: ...
+
+    async def explain(self, stage: str) -> StageExplanation: ...
+
+    async def events_since(self, version: int) -> EventBatch: ...
+
+    async def set_on_error(self, mode: Literal["fail", "keep_going"]) -> bool: ...
+
+    async def diff_output(
+        self,
+        path: str,
+        old_hash: str | None,
+        new_hash: str | None,
+        *,
+        max_rows: int = 50,
+    ) -> dict[str, object]: ...
+
+
+class PivotClient(PivotRpc, Protocol):
+    """Full client with transport + RPC."""
+
+    async def connect(self, socket_path: Path) -> None: ...
+
+    async def disconnect(self) -> None: ...

pivot_tui/diff.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, override
+
+import rich.markup
+import textual.app
+import textual.binding
+import textual.containers
+import textual.widgets
+
+from pivot.types import ChangeType, DataDiffResult, RowChange, SchemaChange
+
+# Rich markup symbols for change types
+STATUS_SYMBOLS_RICH: dict[ChangeType, str] = {
+    ChangeType.ADDED: "[green]+[/]",
+    ChangeType.REMOVED: "[red]-[/]",
+    ChangeType.MODIFIED: "[yellow]~[/]",
+}
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class DiffSummaryPanel(textual.widgets.Static):
+    """Shows diff summary: row counts, column changes, reorder-only status."""
+
+    _result: DataDiffResult
+
+    def __init__(self, result: DataDiffResult) -> None:
+        super().__init__()
+        self._result = result
+
+    @override
+    def compose(self) -> textual.app.ComposeResult:  # pragma: no cover
+        summary_lines = list[str]()
+
+        # File path and status
+        escaped_path = rich.markup.escape(self._result["path"])
+        if self._result["reorder_only"]:
+            summary_lines.append(f"[bold blue]{escaped_path}[/] - REORDER ONLY")
+            summary_lines.append("[dim]Same content, different row order[/]")
+        else:
+            summary_lines.append(f"[bold]{escaped_path}[/]")
+
+        # Row counts
+        old_rows = self._result["old_rows"]
+        new_rows = self._result["new_rows"]
+        if old_rows is not None and new_rows is not None:
+            diff = new_rows - old_rows
+            if diff > 0:
+                diff_str = f"[green]+{diff}[/]"
+            elif diff < 0:
+                diff_str = f"[red]{diff}[/]"
+            else:
+                diff_str = "0"
+            summary_lines.append(f"Rows: {old_rows:,} -> {new_rows:,} ({diff_str})")
+        elif old_rows is not None:
+            summary_lines.append(f"Rows: {old_rows:,} [red](removed)[/]")
+        elif new_rows is not None:
+            summary_lines.append(f"Rows: {new_rows:,} [green](added)[/]")
+
+        # Column counts
+        old_cols = self._result["old_cols"]
+        new_cols = self._result["new_cols"]
+        if old_cols is not None and new_cols is not None:
+            added = len([c for c in new_cols if c not in old_cols])
+            removed = len([c for c in old_cols if c not in new_cols])
+            parts = list[str]()
+            if added:
+                parts.append(f"[green]+{added} added[/]")
+            if removed:
+                parts.append(f"[red]-{removed} removed[/]")
+            col_info = f"{len(old_cols)} -> {len(new_cols)}"
+            if parts:
+                col_info += f" ({', '.join(parts)})"
+            summary_lines.append(f"Columns: {col_info}")
+
+        # Row change summary
+        row_changes = self._result["row_changes"]
+        if row_changes:
+            added = sum(1 for r in row_changes if r["change_type"] == ChangeType.ADDED)
+            removed = sum(1 for r in row_changes if r["change_type"] == ChangeType.REMOVED)
+            modified = sum(1 for r in row_changes if r["change_type"] == ChangeType.MODIFIED)
+            parts = list[str]()
+            if added:
+                parts.append(f"[green]+{added}[/]")
+            if removed:
+                parts.append(f"[red]-{removed}[/]")
+            if modified:
+                parts.append(f"[yellow]~{modified}[/]")
+            if self._result["truncated"]:
+                parts.append("[dim](truncated)[/]")
+            summary_lines.append(f"Changes: {', '.join(parts)}")
+
+        yield textual.widgets.Static("\n".join(summary_lines))
+
+
+class SchemaChangesTable(textual.widgets.DataTable[str]):
+    """Table showing schema (column) changes."""
+
+    _changes: list[SchemaChange]
+
+    def __init__(self, changes: list[SchemaChange]) -> None:
+        super().__init__()
+        self._changes = changes
+
+    @override
+    def on_mount(self) -> None:  # pragma: no cover
+        self.add_columns("Status", "Column", "Old Type", "New Type")
+        for change in self._changes:
+            status = STATUS_SYMBOLS_RICH.get(change["change_type"], "?")
+            self.add_row(
+                status,
+                change["column"],
+                change["old_dtype"] or "-",
+                change["new_dtype"] or "-",
+            )
+
+
+class RowChangesTable(textual.widgets.DataTable[str]):
+    """Table showing row-level changes."""
+
+    _changes: list[RowChange]
+    _columns: list[str]
+
+    def __init__(self, changes: list[RowChange], columns: list[str]) -> None:
+        super().__init__()
+        self._changes = changes
+        self._columns = columns
+
+    @override
+    def on_mount(self) -> None:  # pragma: no cover
+        # Add columns: Status, Key, then all data columns
+        self.add_columns("", "Key", *self._columns)
+
+        for change in self._changes:
+            status = STATUS_SYMBOLS_RICH.get(change["change_type"], "?")
+            key = str(change["key"])
+            row_data = [status, key]
+
+            # Build column values with change highlighting
+            for col in self._columns:
+                old_val = change["old_values"].get(col) if change["old_values"] else None
+                new_val = change["new_values"].get(col) if change["new_values"] else None
+
+                match change["change_type"]:
+                    case ChangeType.ADDED:
+                        row_data.append(f"[green]{new_val}[/]")
+                    case ChangeType.REMOVED:
+                        row_data.append(f"[red]{old_val}[/]")
+                    case _ if old_val != new_val:
+                        row_data.append(f"[yellow]{old_val} -> {new_val}[/]")
+                    case _:
+                        row_data.append(str(new_val) if new_val is not None else "")
+
+            self.add_row(*row_data)
+
+
+class FileDiffScreen(textual.widgets.Static):
+    """Screen showing diff for a single file."""
+
+    _result: DataDiffResult
+
+    def __init__(self, result: DataDiffResult) -> None:
+        super().__init__()
+        self._result = result
+
+    @override
+    def compose(self) -> textual.app.ComposeResult:  # pragma: no cover
+        yield DiffSummaryPanel(self._result)
+
+        # Schema changes section
+        if self._result["schema_changes"]:
+            yield textual.widgets.Static("[bold]Schema Changes[/]")
+            yield SchemaChangesTable(self._result["schema_changes"])
+
+        # Row changes section
+        if self._result["row_changes"] and not self._result["summary_only"]:
+            yield textual.widgets.Static("[bold]Row Changes[/]")
+            columns = self._result["new_cols"] or self._result["old_cols"] or []
+            yield RowChangesTable(self._result["row_changes"], columns)
+        elif self._result["summary_only"]:
+            yield textual.widgets.Static(
+                "[dim]Row-level diff not available (file too large or --summary used)[/]"
+            )
+
+
+class DataDiffApp(textual.app.App[None]):
+    """Interactive data diff viewer.
+
+    Accepts pre-computed DataDiffResult list — all diff computation
+    happens before the app is created (typically via PivotClient.diff_output).
+    """
+
+    CSS: ClassVar[str] = """
+    DiffSummaryPanel {
+        padding: 1;
+        border: solid green;
+        margin-bottom: 1;
+    }
+
+    SchemaChangesTable {
+        height: auto;
+        max-height: 10;
+        margin-bottom: 1;
+    }
+
+    RowChangesTable {
+        height: 1fr;
+    }
+
+    .added { color: green; }
+    .removed { color: red; }
+    .modified { color: yellow; }
+    .reorder-only { color: blue; }
+    """
+
+    BINDINGS: ClassVar[list[textual.binding.BindingType]] = [
+        textual.binding.Binding("q", "quit", "Quit"),
+        textual.binding.Binding("j", "scroll_down", "Down"),
+        textual.binding.Binding("k", "scroll_up", "Up"),
+        textual.binding.Binding("n", "next_file", "Next file"),
+        textual.binding.Binding("p", "prev_file", "Prev file"),
+    ]
+
+    _results: list[DataDiffResult]
+    _current_idx: int
+
+    def __init__(self, results: Sequence[DataDiffResult]) -> None:
+        super().__init__()
+        self._results = list(results)
+        self._current_idx = 0
+
+    @override
+    def compose(self) -> textual.app.ComposeResult:  # pragma: no cover
+        yield textual.widgets.Header()
+        yield textual.containers.VerticalScroll(id="main-content")
+        yield textual.widgets.Footer()
+
+    async def on_mount(self) -> None:  # pragma: no cover
+        self._show_current_file()
+
+    def _show_current_file(self) -> None:  # pragma: no cover
+        """Display the current file's diff."""
+        if not self._results:
+            return
+
+        content = self.query_one("#main-content", textual.containers.VerticalScroll)
+        content.remove_children()
+
+        result = self._results[self._current_idx]
+        content.mount(FileDiffScreen(result))
+
+        # Update title
+        total = len(self._results)
+        current = self._current_idx + 1
+        self.title = f"pivot data diff ({current}/{total}): {result['path']}"  # pyright: ignore[reportUnannotatedClassAttribute]
+
+    def action_next_file(self) -> None:  # pragma: no cover
+        """Move to next file."""
+        if self._current_idx < len(self._results) - 1:
+            self._current_idx += 1
+            self._show_current_file()
+
+    def action_prev_file(self) -> None:  # pragma: no cover
+        """Move to previous file."""
+        if self._current_idx > 0:
+            self._current_idx -= 1
+            self._show_current_file()
+
+    def action_scroll_down(self) -> None:  # pragma: no cover
+        """Scroll down."""
+        content = self.query_one("#main-content", textual.containers.VerticalScroll)
+        content.scroll_down()
+
+    def action_scroll_up(self) -> None:  # pragma: no cover
+        """Scroll up."""
+        content = self.query_one("#main-content", textual.containers.VerticalScroll)
+        content.scroll_up()
+
+
+def run_diff_app(results: Sequence[DataDiffResult]) -> None:  # pragma: no cover
+    """Entry point for TUI.
+
+    Args:
+        results: Pre-computed diff results. The caller (e.g. CLI `pivot diff`
+                 command) is responsible for computing diffs before passing them.
+    """
+    app = DataDiffApp(results)
+    app.run()