patchfeld 0.2.0__py3-none-any.whl

patchfeld/widgets/system_usage.py

@@ -0,0 +1,244 @@
+"""SystemUsage widget — compact CPU + RAM gauges with auto-refresh.
+
+Single-row layout: ``CPU  23.4% [▰▰▰▱▱…]   RAM  8.4/16.0 GiB [▰▰▰▰…]``.
+
+`psutil` is preferred when present (cleanest, cross-platform). When absent
+the widget falls back to non-blocking ``top -l 1 -n 0`` + ``vm_stat`` +
+``sysctl hw.memsize`` shell-outs on macOS via
+``asyncio.create_subprocess_exec`` so the Textual event loop is never
+blocked. On unsupported platforms without psutil, the widget renders an
+error banner and stops scheduling refreshes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import sys
+from dataclasses import dataclass
+
+from textual.widgets import Static
+
+
+# Try psutil but never require it — patchfeld's deps stay minimal. If a user
+# happens to have psutil in their venv (e.g. via a transitive dep), we use
+# it; otherwise we shell out on macOS.
+try:
+    import psutil  # type: ignore
+    _HAS_PSUTIL = True
+except ImportError:
+    psutil = None  # type: ignore
+    _HAS_PSUTIL = False
+
+
+_FILLED = "▰"
+_EMPTY = "▱"
+_GIB = 1024 ** 3
+
+
+@dataclass
+class _Sample:
+    cpu_pct: float
+    ram_used_gib: float
+    ram_total_gib: float
+
+    @property
+    def ram_pct(self) -> float:
+        if self.ram_total_gib <= 0:
+            return 0.0
+        return 100.0 * self.ram_used_gib / self.ram_total_gib
+
+
+def _color_for(pct: float) -> str:
+    if pct < 50:
+        return "green"
+    if pct < 80:
+        return "yellow"
+    return "red"
+
+
+def _bar(pct: float, width: int) -> str:
+    pct = max(0.0, min(100.0, pct))
+    filled = int(round(pct / 100.0 * width))
+    filled = max(0, min(width, filled))
+    color = _color_for(pct)
+    return (
+        f"[{color}]{_FILLED * filled}[/]"
+        f"[dim]{_EMPTY * (width - filled)}[/]"
+    )
+
+
+# --------------------------------------------------------------- macOS shells
+
+_VMSTAT_PAGE_SIZE_RE = re.compile(r"page size of (\d+) bytes")
+_VMSTAT_LINE_RE = re.compile(r"^([^:]+):\s+(\d+)")
+_TOP_CPU_RE = re.compile(
+    r"CPU usage:\s+([\d.]+)%\s+user,\s+([\d.]+)%\s+sys,\s+([\d.]+)%\s+idle"
+)
+
+
+async def _run(*argv: str) -> str:
+    """Run a command without blocking the event loop; return stdout text."""
+    proc = await asyncio.create_subprocess_exec(
+        *argv,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.DEVNULL,
+    )
+    out, _ = await proc.communicate()
+    return out.decode("utf-8", errors="replace")
+
+
+async def _macos_cpu_pct() -> float:
+    """Parse ``top -l 1 -n 0`` for the CPU usage line.
+
+    `top` already samples internally; ``user + sys`` is equivalent to
+    ``100 - idle`` within rounding, and is more robust to spaces/punctuation
+    drift than parsing the idle field.
+    """
+    text = await _run("top", "-l", "1", "-n", "0")
+    m = _TOP_CPU_RE.search(text)
+    if not m:
+        raise RuntimeError("could not parse CPU usage from `top`")
+    return float(m.group(1)) + float(m.group(2))
+
+
+async def _macos_ram_gib() -> tuple[float, float]:
+    """Return ``(used_gib, total_gib)`` using ``vm_stat`` + ``sysctl``.
+
+    ``used = (active + wired_down + occupied_by_compressor) × page_size`` —
+    matches Activity Monitor's "Memory Used" closely. Page size is read from
+    the ``vm_stat`` header (16 KiB on Apple Silicon, 4 KiB on Intel).
+    """
+    vm_text, mem_text = await asyncio.gather(
+        _run("vm_stat"),
+        _run("sysctl", "-n", "hw.memsize"),
+    )
+
+    page_size = 4096
+    m = _VMSTAT_PAGE_SIZE_RE.search(vm_text)
+    if m:
+        page_size = int(m.group(1))
+
+    pages: dict[str, int] = {}
+    for line in vm_text.splitlines():
+        mm = _VMSTAT_LINE_RE.match(line)
+        if mm:
+            pages[mm.group(1).strip().lower()] = int(mm.group(2))
+
+    active = pages.get("pages active", 0)
+    wired = pages.get("pages wired down", 0)
+    compressed = pages.get("pages occupied by compressor", 0)
+    used_bytes = (active + wired + compressed) * page_size
+
+    total_bytes = int(mem_text.strip() or "0")
+    if total_bytes <= 0:
+        raise RuntimeError("hw.memsize returned 0")
+
+    return used_bytes / _GIB, total_bytes / _GIB
+
+
+async def _sample_shellout() -> _Sample:
+    cpu, ram = await asyncio.gather(_macos_cpu_pct(), _macos_ram_gib())
+    used, total = ram
+    return _Sample(cpu_pct=cpu, ram_used_gib=used, ram_total_gib=total)
+
+
+async def _sample_psutil() -> _Sample:
+    cpu = psutil.cpu_percent(interval=None)  # type: ignore[union-attr]
+    vm = psutil.virtual_memory()  # type: ignore[union-attr]
+    return _Sample(
+        cpu_pct=float(cpu),
+        ram_used_gib=vm.used / _GIB,
+        ram_total_gib=vm.total / _GIB,
+    )
+
+
+# ----------------------------------------------------------------- the widget
+
+
+class SystemUsage(Static):
+    """Single-row CPU + RAM gauge that refreshes itself.
+
+    ``interval`` (seconds, clamped >= 0.25, default 1.5) controls refresh
+    cadence. ``bar_width`` (cells, clamped >= 2, default 12) controls the
+    width of each progress bar.
+    """
+
+    DEFAULT_CSS = """
+    SystemUsage {
+        height: auto;
+        min-height: 1;
+        padding: 0 1;
+        content-align: left middle;
+    }
+    """
+
+    def __init__(
+        self,
+        *,
+        interval: float = 1.5,
+        bar_width: int = 12,
+        **kwargs,
+    ) -> None:
+        super().__init__("CPU  …   RAM  …", **kwargs)
+        self._interval = max(0.25, float(interval))
+        self._bar_width = max(2, int(bar_width))
+        self._supported = _HAS_PSUTIL or sys.platform == "darwin"
+        self._source = "psutil" if _HAS_PSUTIL else "shell"
+        self._timer = None
+
+    def on_mount(self) -> None:
+        # Prime psutil so the very first sample isn't 0.0 (psutil's
+        # cpu_percent needs a baseline tick to compute deltas against).
+        if _HAS_PSUTIL:
+            try:
+                psutil.cpu_percent(interval=None)  # type: ignore[union-attr]
+            except Exception:
+                pass
+
+        if not self._supported:
+            self._show_error(
+                f"unsupported platform: {sys.platform} (install psutil)"
+            )
+            return
+
+        self.border_title = f"system — {self._source}"
+        # Kick one immediate refresh, then schedule periodic ones.
+        self.run_worker(self._tick(), exclusive=True)
+        self._timer = self.set_interval(self._interval, self._schedule_tick)
+
+    def _schedule_tick(self) -> None:
+        # `set_interval` fires on the event loop; offload the actual sample
+        # to a worker so a slow shell-out can never delay the next tick.
+        self.run_worker(self._tick(), exclusive=True)
+
+    async def _tick(self) -> None:
+        try:
+            if _HAS_PSUTIL:
+                sample = await _sample_psutil()
+            else:
+                sample = await _sample_shellout()
+        except Exception as exc:  # never raise into the layout
+            self._show_error(str(exc))
+            return
+        self._show_sample(sample)
+
+    # Named ``_show_*`` rather than ``_render*`` to avoid colliding with
+    # ``Widget._render`` (which has a different signature/return shape).
+    def _show_sample(self, s: _Sample) -> None:
+        cpu_bar = _bar(s.cpu_pct, self._bar_width)
+        ram_bar = _bar(s.ram_pct, self._bar_width)
+        cpu_str = f"[b]CPU[/b] {s.cpu_pct:5.1f}% {cpu_bar}"
+        ram_str = (
+            f"[b]RAM[/b] {s.ram_used_gib:5.1f}/{s.ram_total_gib:.1f} GiB "
+            f"{ram_bar}"
+        )
+        self.update(f"{cpu_str}   {ram_str}")
+        # Recover from a transient error: title might still say "error".
+        if self.border_title and "error" in self.border_title:
+            self.border_title = f"system — {self._source}"
+
+    def _show_error(self, msg: str) -> None:
+        self.update("CPU  ?   RAM  ?")
+        # Truncate so the border title stays compact.
+        self.border_title = f"system — error: {msg[:80]}"

patchfeld/widgets/terminal.py

@@ -0,0 +1,251 @@
+import asyncio
+import os
+import select
+
+from textual.app import ComposeResult
+from textual.containers import Container
+from textual.widgets import Static
+
+import ptyprocess
+import pyte
+
+from patchfeld.widgets._terminal_keys import encode_key
+from patchfeld.widgets._terminal_render import render_screen
+
+
+def _default_command() -> list[str]:
+    return [os.environ.get("SHELL", "/bin/sh")]
+
+
+class Terminal(Container):
+    """Real PTY hosted in a Textual panel.
+
+    Spawns a subprocess via ptyprocess.PtyProcessUnicode, feeds output
+    through pyte for ANSI emulation, and re-renders whenever the PTY fd
+    becomes readable via asyncio.add_reader. Anything typed here is
+    OPAQUE to the orchestrator (intentional escape-hatch behavior — use
+    this for an interactive `claude` CLI session inside Patchfeld).
+
+    Props:
+      command: argv list (default: [$SHELL])
+      cwd: working directory (default: process cwd)
+      env: extra env vars merged into os.environ
+
+    Limitations: no mouse forwarding; no bracketed paste; no Kitty
+    keyboard protocol. POSIX-only (ptyprocess).
+    """
+
+    DEFAULT_CSS = """
+    Terminal {
+        border: round $surface-lighten-2;
+        padding: 0 1;
+        background: black;
+        color: white;
+    }
+    Terminal Static {
+        background: black;
+    }
+    """
+
+    can_focus = True
+
+    DEFAULT_COLS = 80
+    DEFAULT_ROWS = 24
+    HISTORY_LINES = 2000  # scrollback rows; memory grows linearly with terminal width
+    READ_BUDGET_BYTES = 64 * 1024  # per-tick drain cap; hitting it is fine — add_reader fires again next tick
+
+    def __init__(
+        self,
+        *,
+        command: list[str] | None = None,
+        cwd: str | None = None,
+        env: dict | None = None,
+    ) -> None:
+        super().__init__()
+        self._command = command or _default_command()
+        self._cwd = cwd
+        environ = dict(os.environ)
+        if env:
+            environ.update(env)
+        self._env = environ
+        self._pty = None
+        self._screen = pyte.HistoryScreen(self.DEFAULT_COLS, self.DEFAULT_ROWS, history=self.HISTORY_LINES)
+        self._stream = pyte.Stream(self._screen)
+        self._timer = None
+        self._reader_registered: bool = False
+        self._last_write: bytes | None = None
+
+    def compose(self) -> ComposeResult:
+        yield Static("", id="terminal-screen")
+
+    def on_mount(self) -> None:
+        try:
+            self._pty = ptyprocess.PtyProcessUnicode.spawn(
+                self._command,
+                cwd=self._cwd,
+                env=self._env,
+                dimensions=(self.DEFAULT_ROWS, self.DEFAULT_COLS),
+            )
+        except Exception as e:
+            self._show_error(f"PTY spawn failed: {e}")
+            return
+        loop = asyncio.get_running_loop()
+        loop.add_reader(self._pty.fd, self._tick)
+        self._reader_registered = True
+
+    def on_resize(self, event) -> None:
+        """Propagate Textual size changes to the PTY and the pyte screen.
+
+        Uses `self.content_size` (region shrunk by the styles gutter, i.e.
+        border + padding) as the authoritative inner dimensions. This is
+        populated by the time the Resize event fires, so we don't need to
+        consult the inner Static (whose auto-height can collapse to 1) or
+        subtract CSS chrome by hand.
+        """
+        if self._pty is None:
+            return
+        inner = self.content_size
+        cols = max(1, inner.width)
+        rows = max(1, inner.height)
+        if cols == self._screen.columns and rows == self._screen.lines:
+            return
+        # setwinsize and screen.resize form a logical pair: if one fails the
+        # other leaves the system in an inconsistent state, so they share a
+        # single guard. No logging in Phase 1 — failures are silent for now.
+        try:
+            self._pty.setwinsize(rows, cols)
+            self._screen.resize(rows, cols)
+        except Exception:
+            return
+        self._refresh()
+
+    def on_unmount(self) -> None:
+        self._teardown()
+
+    def _teardown(self) -> None:
+        if self._reader_registered and self._pty is not None:
+            try:
+                asyncio.get_running_loop().remove_reader(self._pty.fd)
+            except Exception:
+                pass
+            self._reader_registered = False
+        if self._timer is not None:
+            try:
+                self._timer.stop()
+            except Exception:
+                pass
+            self._timer = None
+        if self._pty is not None:
+            try:
+                self._pty.close(force=True)
+            except Exception:
+                pass
+            self._pty = None
+
+    def _announce_exit(self) -> None:
+        # Capture status if available before teardown clears _pty.
+        # Banner status: int (real exit code), or "?" sentinel when we can't determine it.
+        status: int | str = "?"
+        if self._pty is not None:
+            try:
+                ex = self._pty.exitstatus
+                if ex is None:
+                    # isalive() polls waitpid(WNOHANG) and populates exitstatus
+                    # as a side effect. Non-blocking; safe even if a grandchild
+                    # inherited the slave fd and is still running.
+                    if not self._pty.isalive():
+                        ex = self._pty.exitstatus
+                if ex is not None:
+                    status = ex
+            except Exception:
+                pass
+        banner = f"\r\n[process exited {status}]\r\n"
+        try:
+            self._stream.feed(banner)
+        except Exception:
+            pass
+        self._teardown()
+        self._refresh()
+
+    def action_restart(self) -> None:
+        """Respawn the subprocess in-place. Safe to call after exit."""
+        if self._pty is not None:
+            # Already running — nothing to do.
+            return
+        # Reset the screen so the old session's tail doesn't accumulate forever.
+        self._screen = pyte.HistoryScreen(
+            self._screen.columns, self._screen.lines, history=self.HISTORY_LINES
+        )
+        self._stream = pyte.Stream(self._screen)
+        self.on_mount()
+
+    def _tick(self) -> None:
+        if self._pty is None:
+            return
+        # Drain everything available without blocking, but bounded so a flooding
+        # child can't starve the asyncio loop. add_reader will fire again next tick.
+        any_data = False
+        bytes_read = 0
+        eof = False
+        while bytes_read < self.READ_BUDGET_BYTES:
+            try:
+                ready, _, _ = select.select([self._pty.fd], [], [], 0)
+                if not ready:
+                    break
+                chunk = self._pty.read(4096)
+            except EOFError:
+                eof = True
+                break
+            except Exception:
+                # TODO(phase 2): surface PTY read errors via _show_error
+                break
+            if not chunk:
+                eof = True
+                break
+            self._stream.feed(chunk)
+            bytes_read += len(chunk)
+            any_data = True
+        if eof:
+            self._announce_exit()
+        elif any_data:
+            self._refresh()
+
+    def _refresh(self) -> None:
+        try:
+            screen = self.query_one("#terminal-screen", Static)
+        except Exception:
+            return
+        text = render_screen(self._screen, show_cursor=True)
+        screen.update(text)
+
+    def _show_error(self, msg: str) -> None:
+        from rich.text import Text
+        try:
+            self.query_one("#terminal-screen", Static).update(Text(msg))
+        except Exception:
+            pass
+
+    def on_key(self, event) -> None:
+        if self._pty is None:
+            return
+        data = encode_key(event.key, event.character)
+        if data is None:
+            return
+        try:
+            # encode_key returns bytes; PtyProcessUnicode.write wraps a utf-8 text
+            # stream, so decode->re-encode is lossless for any output of encode_key
+            # (all paths produce well-formed utf-8).
+            self._pty.write(data.decode("utf-8", errors="replace"))
+        except Exception:
+            # TODO(phase 2): surface PTY write errors via _show_error
+            return
+        self._last_write = data
+        event.stop()
+
+    @classmethod
+    def default_border_title(cls, props: dict) -> str:
+        from pathlib import Path as _P
+        command = props.get("command")
+        if command and isinstance(command, list) and len(command) > 0:
+            return f"Terminal: {_P(command[0]).name}"
+        return "Terminal"

patchfeld/widgets/theme_switcher.py

@@ -0,0 +1,63 @@
+from textual.binding import Binding
+from textual.containers import Container
+from textual.screen import ModalScreen
+from textual.widgets import Footer, Label, ListItem, ListView
+
+from patchfeld.persistence.themes_store import NamedThemesStore
+
+
+class ThemeSwitcherScreen(ModalScreen[str | None]):
+    """Pick a theme. Esc dismisses with None; selecting dismisses with the name."""
+
+    DEFAULT_CSS = """
+    ThemeSwitcherScreen {
+        align: center middle;
+    }
+    ThemeSwitcherScreen > Container {
+        width: 50%;
+        height: 60%;
+        border: thick $primary;
+        background: $surface;
+        padding: 1 2;
+    }
+    ThemeSwitcherScreen ListView {
+        height: 1fr;
+    }
+    """
+
+    BINDINGS = [Binding("escape", "dismiss_none", "cancel")]
+
+    def __init__(
+        self,
+        *,
+        store: NamedThemesStore,
+        available_builtins: list[str],
+        active: str,
+    ) -> None:
+        super().__init__()
+        self._store = store
+        self._builtins = list(available_builtins)
+        self._active = active
+
+    def compose(self):
+        items: list[ListItem] = []
+        for name in self._store.list():
+            label = f"* {name}" if name == self._active else f"  {name}"
+            items.append(ListItem(Label(label), name=name))
+        if self._builtins:
+            items.append(ListItem(Label("─ built-ins ─"), name=None))
+        for name in self._builtins:
+            label = f"* {name}" if name == self._active else f"  {name}"
+            items.append(ListItem(Label(label), name=name))
+        with Container():
+            yield Label("Load theme:")
+            yield ListView(*items)
+            yield Footer()
+
+    def on_list_view_selected(self, event: ListView.Selected) -> None:
+        if event.item.name is None:
+            return  # separator row — ignore
+        self.dismiss(event.item.name)
+
+    def action_dismiss_none(self) -> None:
+        self.dismiss(None)

patchfeld/widgets/transcript_screen.py

@@ -0,0 +1,39 @@
+from textual.binding import Binding
+from textual.containers import Container
+from textual.screen import ModalScreen
+from textual.widgets import Footer
+
+from patchfeld.events import EventBus
+from patchfeld.widgets.agent_transcript import AgentTranscript
+
+
+class TranscriptScreen(ModalScreen[None]):
+    """Modal overlay showing one agent's transcript. Esc to dismiss."""
+
+    DEFAULT_CSS = """
+    TranscriptScreen {
+        align: center middle;
+    }
+    TranscriptScreen > Container {
+        width: 80%;
+        height: 80%;
+        border: thick $primary;
+        background: $surface;
+        padding: 1 2;
+    }
+    """
+
+    BINDINGS = [Binding("escape", "dismiss", "close")]
+
+    def __init__(self, agent_id: str, event_bus: EventBus | None = None) -> None:
+        super().__init__()
+        self._agent_id = agent_id
+        self._bus = event_bus
+
+    def compose(self):
+        with Container():
+            yield AgentTranscript(agent_id=self._agent_id, event_bus=self._bus)
+            yield Footer()
+
+    def action_dismiss(self) -> None:
+        self.dismiss(None)

patchfeld/workspace/__init__.py

@@ -0,0 +1,3 @@
+from patchfeld.workspace.spec import Tab, Workspace, workspace_from_layout
+
+__all__ = ["Tab", "Workspace", "workspace_from_layout"]

patchfeld/workspace/spec.py

@@ -0,0 +1,72 @@
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from patchfeld.layout.spec import LayoutSpec, Node, Panel, Tabs
+
+
+class Tab(BaseModel):
+    """One app-level tab. Owns its own LayoutSpec, which is independently
+    mutable. `id` is stable across the tab's lifetime and used by
+    switch_tab/close_tab tool calls. `title` is the user-facing tab-strip
+    label."""
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    title: str
+    layout: LayoutSpec
+
+
+class Workspace(BaseModel):
+    """Top-level container. Holds a list of Tabs and an active id.
+
+    Invariants:
+    - Non-empty tab list.
+    - `active` references one of `tabs[].id`.
+    - At least one OrchestratorChat panel exists across all tabs combined.
+    - Tab ids are unique.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    version: int = 1
+    tabs: list[Tab] = Field(min_length=1)
+    active: str
+    active_theme: str | None = None
+
+    @model_validator(mode="after")
+    def _validate(self) -> "Workspace":
+        ids = [t.id for t in self.tabs]
+        if len(ids) != len(set(ids)):
+            raise ValueError(f"duplicate tab id in {ids}")
+        if self.active not in set(ids):
+            raise ValueError(
+                f"active tab id {self.active!r} not in tab ids {ids}"
+            )
+        if not any(_contains_chat(t.layout.layout) for t in self.tabs):
+            raise ValueError(
+                "Workspace must contain at least one OrchestratorChat panel "
+                "across all tabs"
+            )
+        return self
+
+
+def _contains_chat(node: Node) -> bool:
+    if isinstance(node, Panel):
+        return node.widget == "OrchestratorChat"
+    if isinstance(node, Tabs):
+        # Tabs.children is list[Panel] (leaf-only invariant in spec.py), so
+        # a flat scan is sufficient — no recursion needed. If Tabs ever
+        # accepts nested containers, this branch must recurse like Container.
+        return any(c.widget == "OrchestratorChat" for c in node.children)
+    # node is Container — exhausted by the discriminated Node union.
+    return any(_contains_chat(c) for c in node.children)
+
+
+def workspace_from_layout(spec: LayoutSpec, *, tab_id: str = "default",
+                          title: str = "default") -> Workspace:
+    """Build a single-tab Workspace wrapping a LayoutSpec — used by app
+    launch to seed the workspace from the built-in dashboard or migrate
+    a legacy layout.json."""
+    return Workspace(
+        version=1,
+        tabs=[Tab(id=tab_id, title=title, layout=spec)],
+        active=tab_id,
+    )