ring-cli 0.2.0__py3-none-any.whl

ring/sources/__init__.py

@@ -0,0 +1,94 @@
+"""Session 來源 package——讓 RiNG 不綁死 Claude Code。
+
+每個工具是一個 ``SessionSource``：core 不認識任何具體工具，只把各 source 吐出的
+``Session`` 收齊、配 tmux 座標、排序。要支援別的 agent CLI＝在這個 package 加一個
+模組、``register_source()`` 註冊，core 零改動（跟 ``focus`` 的 focuser 同一套設計）。
+"""
+
+from __future__ import annotations
+
+import ring.registry as registry
+from ring.registry import Session, Status
+from ring.sources.base import SessionSource
+from ring.sources.claude_code import source as _claude_code
+from ring.sources.codex import source as _codex
+from ring.sources.hook_registry import source as _hook_registry
+
+# 註冊表（順序＝彙整順序）。hook registry 先於 zero-config source，精準事件優先。
+_SOURCES: list[SessionSource] = [_hook_registry, _claude_code, _codex]
+
+
+def register_source(source: SessionSource, *, first: bool = False) -> None:
+    """外部擴充入口：註冊一個自訂 session 來源。"""
+    if first:
+        _SOURCES.insert(0, source)
+    else:
+        _SOURCES.append(source)
+
+
+def sources() -> list[SessionSource]:
+    """目前已註冊的來源。"""
+    return list(_SOURCES)
+
+
+def discover_sessions() -> list[Session]:
+    """場館點名：彙整所有來源的 session，配 tmux 座標、排序（等你的排最上面）。"""
+    merged: dict[str, Session] = {}
+    for source in _SOURCES:
+        for s in source.discover():
+            current = merged.get(s.session_id)
+            merged[s.session_id] = s if current is None else _merge_duplicate_session(current, s)
+    found = list(merged.values())
+    targets = registry._tmux_targets()
+    for s in found:
+        s.tmux_target = targets.get(s.cwd)
+    found.sort(key=lambda s: (s.status.rank, s.idle_for))
+    return found
+
+
+def _merge_duplicate_session(current: Session, candidate: Session) -> Session:
+    """同一 session 來自多個來源時合併。
+
+    hook registry 通常最精準，所以預設保留先到的 hook row。不過 Claude Code 有些
+    action-required 狀態之後未必會送出能清掉 waiting 的 hook；如果 zero-config scan
+    已看到同一 session 有更新紀錄且不再是 WAITING，就用 scan 清掉 stale waiting，
+    同時保留 hook 拿到的 tty，避免跳轉能力退化。
+    """
+    if (
+        current.source == "hook"
+        and current.status is Status.WAITING
+        and candidate.provider == current.provider
+        and candidate.status is not Status.WAITING
+        and candidate.last_active > current.last_active
+    ):
+        if not candidate.tty:
+            candidate.tty = current.tty
+        if not candidate.tmux_target:
+            candidate.tmux_target = current.tmux_target
+        return candidate
+    return current
+
+
+def get_by_id(session_id: str) -> Session | None:
+    """現查現給：重跑 discover_sessions() 後 filter 出指定 session_id。
+
+    每次呼叫都重跑 discover，不快取舊 Session——scan 的 tty 只在「該 cwd 剛好一個
+    live claude」才填，舊 Session 的 tty 可能已失效（例如點擊通知時），
+    必須重新 discover 才能拿到當下有效的 tty。
+
+    :param session_id: 要查詢的 session id。
+    :returns: 找到時回對應 Session；找不到回 None。
+    """
+    for s in discover_sessions():
+        if s.session_id == session_id:
+            return s
+    return None
+
+
+__all__ = [
+    "SessionSource",
+    "discover_sessions",
+    "get_by_id",
+    "register_source",
+    "sources",
+]

ring/sources/base.py

@@ -0,0 +1,17 @@
+"""SessionSource 協定（跟 ``focus/base``、``notify/base`` 同一套設計）。
+
+``Session`` 本身已是工具中立的（session_id / cwd / status / last_action / tty…），
+所以新 source 只要負責「怎麼找到自己的 session、怎麼填這個 model」。
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ring.registry import Session
+
+
+class SessionSource(Protocol):
+    name: str
+
+    def discover(self) -> list[Session]: ...

ring/sources/claude_code.py

@@ -0,0 +1,23 @@
+"""Claude Code：掃 ``~/.claude/projects`` 的 JSONL。"""
+
+from __future__ import annotations
+
+import ring.registry as registry
+from ring.registry import Session
+
+
+class ClaudeCodeSource:
+    name = "claude-code"
+
+    def discover(self) -> list[Session]:
+        procs = registry._claude_procs()
+        merged: dict[str, Session] = {}
+        for s in registry._scan_sessions(procs):
+            merged.setdefault(s.session_id, s)
+        existing = list(merged.values())
+        for s in registry._synthetic_sessions(procs, existing):
+            merged.setdefault(s.session_id, s)  # 合成列只填無 row 的 cwd
+        return list(merged.values())
+
+
+source = ClaudeCodeSource()

ring/sources/codex.py

@@ -0,0 +1,16 @@
+"""Codex CLI：讀 ``~/.codex/state_5.sqlite`` threads，並用 live ``codex`` process 配 tty。"""
+
+from __future__ import annotations
+
+import ring.registry as registry
+from ring.registry import Session
+
+
+class CodexSource:
+    name = "codex"
+
+    def discover(self) -> list[Session]:
+        return registry._codex_threads(registry._codex_procs())
+
+
+source = CodexSource()

ring/sources/hook_registry.py

@@ -0,0 +1,16 @@
+"""RiNG hook registry：所有 provider 的精準事件來源。"""
+
+from __future__ import annotations
+
+import ring.registry as registry
+from ring.registry import Session
+
+
+class HookRegistrySource:
+    name = "hook"
+
+    def discover(self) -> list[Session]:
+        return registry._hook_sessions(procs_by_provider=registry.collect_provider_procs())
+
+
+source = HookRegistrySource()

ring/tui.py

@@ -0,0 +1,360 @@
+"""RiNG 的 Textual live TUI——鍵盤導覽 + tmux / iTerm2 一鍵跳。
+
+需要 textual（``pip install 'ring[tui]'``）。沒裝時 CLI 會自動退回 Rich poll。
+
+鍵：↑/↓（或 vim 的 j/k、g/G 跳頭尾）選 session、Enter/Space 跳到它所在的終端、
+a 切換是否顯示已離場、r 刷新、q 離場。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import ClassVar
+
+from rich.text import Text
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import Vertical
+from textual.screen import ModalScreen
+from textual.widgets import DataTable, Footer, Header, Input, Static
+
+from ring.cli import (
+    _LOC_MAX,
+    _STATUS_STYLE,
+    _header,
+    _middle_truncate,
+    _rel,
+    board,
+    labeled_project,
+    provider_label,
+    show_tool_column,
+    status_label,
+)
+from ring.config import get_config
+from ring.focus import jump as focus_jump
+from ring.i18n import gettext as _
+from ring.i18n import set_lang
+from ring.ipc import clear_tui_presence, read_focus_request, write_tui_presence
+from ring.labels import get_label, load_labels, set_label
+from ring.notify import notify_waiting
+from ring.registry import Session, Status, running_agent_pids
+from ring.watcher import WaitingAlertScheduler
+
+_ORDER = (Status.WAITING, Status.WORKING, Status.IDLE, Status.ENDED)
+
+
+class _Grid(DataTable[Text]):
+    """看板表格。在 DataTable 既有的方向鍵之外，加上 vim 風的 j/k/g/G 導覽。
+
+    全部 ``show=False``——footer 保持乾淨，這些只是給手習慣 vim 的人的隱藏快捷。
+    對應 DataTable 既有 action：j/k=cursor_down/up、g/G=scroll_top/bottom（cursor_type
+    為 row 時，這兩個會把游標移到第一／最後一列，正是 vim 的語意）。
+    """
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("j", "cursor_down", show=False),
+        Binding("k", "cursor_up", show=False),
+        Binding("g", "scroll_top", show=False),
+        Binding("G", "scroll_bottom", show=False),
+    ]
+
+
+class _NameModal(ModalScreen[str | None]):
+    """為選中的 session 命名的小浮層。Enter 存、Esc 取消、清空移除。
+
+    dismiss 回傳：輸入字串（含空字串＝清除標籤）或 ``None``（取消，不動）。
+    """
+
+    DEFAULT_CSS = """
+    _NameModal {
+        align: center middle;
+    }
+    _NameModal #name-box {
+        width: 60;
+        height: auto;
+        padding: 1 2;
+        background: $panel;
+        border: round $accent;
+    }
+    """
+
+    def __init__(self, project: str, current: str) -> None:
+        super().__init__()
+        self._project = project
+        self._current = current
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="name-box"):
+            yield Static(_("為 {project} 命名（Enter 存、Esc 取消、清空移除）", project=self._project))
+            yield Input(value=self._current, placeholder=_("這個 session 在做什麼…"))
+
+    def on_mount(self) -> None:
+        self.query_one(Input).focus()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        self.dismiss(event.value)
+
+    def key_escape(self) -> None:
+        self.dismiss(None)
+
+
+class RingApp(App[None]):
+    """場館的即時看板。"""
+
+    # 按鍵說明在 import 時定下——cli 會在 import 本模組前先 set_lang()，所以吃得到 --lang。
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("q", "quit", _("離場")),
+        Binding("r", "refresh_now", _("刷新")),
+        Binding("a", "toggle_all", _("含已離場")),
+        Binding("n", "name_session", _("命名")),
+        Binding("enter", "jump", _("跳過去")),
+        Binding("space", "jump", _("跳過去"), show=False),
+    ]
+
+    def __init__(self, lang: str | None = None, interval: float = 2.0, show_all: bool = False) -> None:
+        super().__init__()
+        if lang is not None:
+            set_lang(lang)
+        self._interval = interval
+        self._show_all = show_all
+        self._sessions: list[Session] = []
+        # 工具欄是否顯示（啟動時依首批 session 決定：全同一個 provider 就省掉）。
+        self._show_tool: bool = True
+        # 通知點過來時指向的 session：那一列要持續醒目標記，直到它離開 WAITING（你回應了）或不在場。
+        self._focused_sid: str | None = None
+        cfg = get_config()
+        self._alerts = WaitingAlertScheduler(cfg.notify_repeat_seconds, cfg.notify_repeat_max)
+        self.title = "RiNG 🎤"
+        # 記下自己的 controlling tty，供 _poll_focus_request activate 視窗用。
+        self._own_tty: str = self._detect_own_tty()
+
+    @staticmethod
+    def _detect_own_tty() -> str:
+        """取得 controlling terminal 的 tty 路徑，取不到就回空字串。"""
+        import sys as _sys
+
+        try:
+            if _sys.stdout.isatty():
+                return os.ttyname(_sys.stdout.fileno())
+        except Exception:
+            pass
+        try:
+            fd = os.open("/dev/tty", os.O_RDONLY | os.O_NOCTTY)
+            try:
+                return os.ttyname(fd)
+            finally:
+                os.close(fd)
+        except Exception:
+            return ""
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        yield Static(id="legend")
+        yield _Grid(id="grid", zebra_stripes=True)
+        yield Static(id="status")
+        yield Footer()
+
+    def _setup_columns(self) -> None:
+        """依 self._show_tool 重建 DataTable 欄位。
+
+        呼叫前須先完成 clear(columns=True)（或首次 mount 還沒有欄位）。
+        """
+        table = self.query_one(DataTable)
+        cols = [_("狀態")]
+        if self._show_tool:
+            cols.append(_("工具"))
+        cols += [_("專案"), _("進度"), _("閒置"), _("去哪"), _("動作")]
+        for label in cols:
+            table.add_column(label)
+
+    def on_mount(self) -> None:
+        # 寫入 presence，讓 `ring focus` 知道 TUI 在跑。
+        write_tui_presence()
+        # 啟動時依首批 session 決定要不要顯示工具欄。
+        self._sessions = board(self._show_all)
+        self._show_tool = show_tool_column(self._sessions)
+        table = self.query_one(DataTable)
+        self._setup_columns()
+        table.cursor_type = "row"
+        table.focus()  # 讓 ↑/↓ 與 Enter 直接作用在表格上
+        self._render_legend()
+        self._reload()
+        self.set_interval(self._interval, self._reload)
+        if not self._hooks_active() and self._has_cwd_collision():
+            self._set_status(_("💡 同專案開了多個 session，裝 hook 跳轉才精準：ring install-hooks"))
+        else:
+            self._set_status(_("↑/↓ 選一列，Enter 或 Space 跳到那個 session 的終端"))
+
+    def on_unmount(self) -> None:
+        # 清除 presence，TUI 離場後 `ring focus` 退回 headless 行為。
+        clear_tui_presence()
+
+    def _set_status(self, text: str) -> None:
+        self.query_one("#status", Static).update(text)
+
+    def _hooks_active(self) -> bool:
+        return any(s.source == "hook" for s in self._sessions)
+
+    def _has_cwd_collision(self) -> bool:
+        """同一個 cwd 有多個還在場的 session → scan 模式分不出 tty，hook 才精準。"""
+        live = [s.cwd for s in self._sessions if s.status is not Status.ENDED]
+        return len(live) != len(set(live))
+
+    def _render_legend(self) -> None:
+        legend = Text(f"{_('圖例')}   ", style="grey50")
+        for status in _ORDER:
+            legend.append(f"{status.marker} {status_label(status)}   ", style=_STATUS_STYLE[status])
+        self.query_one("#legend", Static).update(legend)
+
+    def _ring_on_waiting_alerts(self, alerts: list[Session]) -> None:
+        """有 session 需要提醒 → RiNG 真的「ring」你（響鈴 + toast 通知）。"""
+        if alerts:
+            self.bell()
+            names = ", ".join(sorted(s.project for s in alerts))
+            self.notify(_("🔔 {names} 在等你回話", names=names), timeout=8)
+
+    def _activate_own_window(self) -> None:
+        """把 RiNG 自己的終端視窗帶到前景（best-effort，失敗安靜吞）。
+
+        複用既有 focuser 鏈（tmux / iTerm2 / Terminal）：用自己的 tty 組一個 self-Session
+        丟給 ``focus_jump``，誰接得住誰來——這樣 tmux 與各 macOS 終端都走同一條路，
+        不必在這裡手寫 AppleScript。
+        """
+        if not self._own_tty:
+            return
+        try:
+            focus_jump(Session("self", "/", Status.WORKING, 0.0, "", "ipc", tty=self._own_tty))
+        except Exception:
+            pass
+
+    def _poll_focus_request(self) -> None:
+        """讀一次 focus-request 檔，有效的話把游標跳過去、持續標記，並 activate 自己視窗。
+
+        1. 讀 focus-request；無 / 過期 / 解析失敗 → 直接回傳（read_focus_request 已消費即焚）。
+        2. activate 自己視窗（複用 focuser 鏈）。
+        3. 在 _sessions 找 session_id → 移游標 + 記住 _focused_sid（那列持續標記直到回應）。
+        4. 找不到 → 走「已不在場」分支，清掉 _focused_sid。
+        """
+        sid = read_focus_request()
+        if sid is None:
+            return
+
+        self._activate_own_window()
+
+        target_row: int | None = None
+        for idx, s in enumerate(self._sessions):
+            if s.session_id == sid:
+                target_row = idx
+                break
+
+        if target_row is not None:
+            self._focused_sid = sid
+            table = self.query_one(DataTable)
+            table.move_cursor(row=target_row)
+            found_session = self._sessions[target_row]
+            msg = _("→ 已跳到 {project}（來自通知）", project=found_session.project)
+            self._set_status(msg)
+            self.notify(msg, timeout=8)
+        else:
+            self._focused_sid = None
+            msg = _("那個 session 已不在場")
+            self._set_status(msg)
+            self.notify(msg, severity="warning", timeout=8)
+
+    def _reload(self) -> None:
+        # 每次刷新都續寫 presence，避免 TUI 開超過 TTL 後 `ring focus` 誤判 TUI 沒在跑、
+        # 退回去跳 session 自己的終端（scan 模式常沒 tty → 跳轉失敗）。
+        write_tui_presence()
+        self._sessions = board(self._show_all)
+        table = self.query_one(DataTable)
+        # cursor 快照要在「任何」clear 之前取：clear(columns=True) 會把 cursor_row reset 成 0。
+        cursor = table.cursor_row
+        # 動態更新工具欄：名單變了（混用 ↔ 全同一種），重建欄位；沒變就省掉欄位重建。
+        new_show_tool = show_tool_column(self._sessions)
+        if new_show_tool != self._show_tool:
+            self._show_tool = new_show_tool
+            table.clear(columns=True)  # columns=True 同時清欄位與資料列
+            self._setup_columns()
+        # 通知指向的 session 一旦離開 WAITING（你回應了）或不在場，就解除醒目標記。
+        if self._focused_sid is not None:
+            cur = next((s for s in self._sessions if s.session_id == self._focused_sid), None)
+            if cur is None or cur.status is not Status.WAITING:
+                self._focused_sid = None
+        alerts = self._alerts.feed(self._sessions)
+        self._ring_on_waiting_alerts(alerts)
+        try:
+            hint = notify_waiting(alerts)
+            if hint:
+                self.notify(hint, timeout=10)
+        except Exception:
+            pass
+        self.sub_title = _header(len(self._sessions), len(running_agent_pids()))
+        labels = load_labels()
+        table.clear()
+        for s in self._sessions:
+            focused = s.session_id == self._focused_sid
+            marker = "👉 " if focused else ""
+            style = f"reverse {_STATUS_STYLE[s.status]}" if focused else _STATUS_STYLE[s.status]
+            status_cell = Text(f"{marker}{s.status.marker} {status_label(s.status)}", style=style)
+            progress = f"{s.todo[0]}/{s.todo[1]}" if s.todo else "·"
+            loc_cell = f"📍{_middle_truncate(s.location, _LOC_MAX)}"
+            project_cell = labeled_project(s.project, labels.get(s.session_id, ""))
+            cells: list[object] = [status_cell]
+            if self._show_tool:
+                cells.append(provider_label(s.provider))
+            cells += [project_cell, progress, _rel(s.idle_for), loc_cell, s.last_action]
+            table.add_row(*cells)
+        if self._sessions:
+            table.move_cursor(row=min(cursor, len(self._sessions) - 1))
+        self._poll_focus_request()
+
+    def _selected(self) -> Session | None:
+        row = self.query_one(DataTable).cursor_row
+        if 0 <= row < len(self._sessions):
+            return self._sessions[row]
+        return None
+
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        # DataTable 被 focus 時會吃掉 Enter（變成 RowSelected），在這裡接、轉成跳轉。
+        self.action_jump()
+
+    def action_name_session(self) -> None:
+        s = self._selected()
+        if s is None:
+            self._set_status(_("（沒有選到 session）"))
+            return
+
+        def _save(label: str | None) -> None:
+            if label is None:
+                return  # Esc 取消，不動
+            set_label(s.session_id, label)
+            self._reload()
+
+        self.push_screen(_NameModal(s.project, get_label(s.session_id)), _save)
+
+    def action_refresh_now(self) -> None:
+        self._reload()
+
+    def action_toggle_all(self) -> None:
+        self._show_all = not self._show_all
+        self._reload()
+
+    def action_jump(self) -> None:
+        s = self._selected()
+        if s is None:
+            self._set_status(_("（沒有選到 session）"))
+            return
+        if s.session_id == self._focused_sid:
+            self._focused_sid = None  # 你已親自跳過去處理，解除通知標記
+        ok, msg = focus_jump(s)
+        if ok:
+            text = _("→ {project}（{where}）", project=s.project, where=msg)
+        else:
+            text = _("{project}：{msg}", project=s.project, msg=msg)
+        self._set_status(text)
+        self.notify(text, severity="information" if ok else "warning", timeout=10)
+
+
+def run_tui(interval: float = 2.0, show_all: bool = False) -> int:
+    RingApp(interval=interval, show_all=show_all).run()
+    return 0

ring/watcher.py

@@ -0,0 +1,107 @@
+"""不依賴 Textual 的「新轉 waiting 偵測器」狀態件。
+
+讓 TUI 與 headless watch() 兩條 loop 共用同一套「某 session 新轉為 waiting」邏輯，
+避免維護兩套可能打架的差異邏輯。完全不 import Textual，可在無 macOS GUI 環境單測。
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from ring.registry import Session, Status
+
+
+class WaitingWatcher:
+    """追蹤 session snapshot 差集，回傳「本輪新轉為 waiting」的清單。
+
+    第一輪（prime 語意）：只記錄當前 waiting set、回空清單，避免啟動瞬間把所有既有
+    waiting session 當「新轉」狂發通知。第二輪起才開始吐差集。
+    """
+
+    def __init__(self) -> None:
+        self._waiting_ids: set[str] = set()
+        self._primed: bool = False
+
+    def feed(self, sessions: list[Session]) -> list[Session]:
+        """餵入當前 snapshot，回傳「本輪新轉為 waiting」的 Session 清單。
+
+        :param sessions: 當前完整 session 快照（通常來自 board() / discover_sessions()）。
+        :returns: 本輪從「非 waiting」轉為「waiting」的 session；第一輪一律回空清單。
+        """
+        current_waiting = {s.session_id for s in sessions if s.status is Status.WAITING}
+        if not self._primed:
+            # 第一輪只記錄，不發通知
+            self._waiting_ids = current_waiting
+            self._primed = True
+            return []
+        newly = current_waiting - self._waiting_ids
+        self._waiting_ids = current_waiting
+        if not newly:
+            return []
+        return [s for s in sessions if s.session_id in newly]
+
+
+@dataclass
+class _AlertState:
+    first_seen: float
+    last_alert: float
+    repeats_sent: int = 0
+
+
+class WaitingAlertScheduler:
+    """決定哪些 waiting session 此輪需要通知。
+
+    第一輪只 prime，不通知既有 waiting；之後新轉 waiting 立即通知，持續 waiting 則依
+    ``repeat_seconds`` 做最多 ``repeat_max`` 次提醒（0 = 不限）。
+    """
+
+    def __init__(
+        self,
+        repeat_seconds: tuple[int, ...] = (),
+        repeat_max: int = 0,
+        *,
+        now: Callable[[], float] = time.time,
+    ) -> None:
+        self._repeat_seconds = repeat_seconds
+        self._repeat_max = max(0, repeat_max)
+        self._now = now
+        self._states: dict[str, _AlertState] = {}
+        self._primed = False
+
+    def feed(self, sessions: list[Session]) -> list[Session]:
+        current = {s.session_id: s for s in sessions if s.status is Status.WAITING}
+        now = self._now()
+
+        if not self._primed:
+            self._states = {sid: _AlertState(first_seen=now, last_alert=now) for sid in current}
+            self._primed = True
+            return []
+
+        due: list[Session] = []
+        next_states: dict[str, _AlertState] = {}
+        for sid, session in current.items():
+            state = self._states.get(sid)
+            if state is None:
+                next_states[sid] = _AlertState(first_seen=now, last_alert=now)
+                due.append(session)
+                continue
+
+            if self._should_repeat(state, now):
+                state.last_alert = now
+                state.repeats_sent += 1
+                due.append(session)
+            next_states[sid] = state
+
+        self._states = next_states
+        return due
+
+    def _should_repeat(self, state: _AlertState, now: float) -> bool:
+        if not self._repeat_seconds:
+            return False
+        if self._repeat_max and state.repeats_sent >= self._repeat_max:
+            return False
+        if state.repeats_sent < len(self._repeat_seconds):
+            return now - state.first_seen >= self._repeat_seconds[state.repeats_sent]
+        return now - state.last_alert >= self._repeat_seconds[-1]