ring-cli 0.2.0__py3-none-any.whl

ring/hook_protocol.py

@@ -0,0 +1,264 @@
+"""Provider-neutral hook event normalization for RiNG.
+
+外部工具只要能把事件 JSON 餵給 ``ring hook``，就能寫入同一份 registry。
+provider adapter 負責把各工具的事件名稱與欄位正規化，registry writer 不需要知道
+Claude Code、Codex 或未來工具的細節。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from ring.registry import Status
+
+
+class HookAdapter(Protocol):
+    """把某個 provider 的 hook payload 正規化成 RiNG event。"""
+
+    provider: str
+    process_names: tuple[str, ...]
+
+    def normalize(self, data: Mapping[str, Any]) -> NormalizedHookEvent | None:
+        """回傳正規化事件；不支援或 payload 不足時回 ``None``。"""
+
+
+@dataclass(frozen=True)
+class NormalizedHookEvent:
+    provider: str
+    event: str
+    session_id: str
+    cwd: str
+    status: Status
+    transcript_path: str = ""
+    tty: str = ""
+    last_action: str = ""
+    waiting_for: str = ""
+
+
+_ALWAYS_STATUS = {
+    "SessionStart": Status.WORKING,
+    "UserPromptSubmit": Status.WORKING,
+    "Stop": Status.IDLE,
+    "SessionEnd": Status.ENDED,
+    "PermissionRequest": Status.WAITING,
+}
+
+_ACTION_REQUIRED_NOTIFICATION_TYPES = {
+    "permission_prompt",
+    "elicitation_dialog",
+}
+
+_ACTION_REQUIRED_WAITING_FOR = {
+    "approval",
+    "choice",
+    "choices",
+    "elicitation",
+    "input",
+    "option",
+    "options",
+    "permission",
+    "question",
+    "questions",
+    "selection",
+    "user",
+    "user_input",
+}
+
+_IDLE_WAITING_FOR = {
+    "",
+    "complete",
+    "done",
+    "idle",
+    "instruction",
+    "next_step",
+    "none",
+    "prompt",
+    "turn_complete",
+    "user_prompt",
+}
+
+
+class CommonHookAdapter:
+    """共用事件語意 adapter。
+
+    適合 Claude Code、Codex，以及未來沿用類似 lifecycle event 的 agent CLI。
+    """
+
+    def __init__(self, provider: str, process_names: tuple[str, ...]) -> None:
+        self.provider = provider
+        self.process_names = process_names
+
+    def normalize(self, data: Mapping[str, Any]) -> NormalizedHookEvent | None:
+        event = _first_str(data, "event", "event_name", "hook_event_name", "hookEventName")
+        sid = _first_str(data, "session_id", "sessionId", "thread_id", "threadId", "id")
+        if not event or not sid:
+            return None
+        status = _ALWAYS_STATUS.get(event)
+        explicit_requires_action = _explicit_requires_action(data)
+        if event == "SessionEnd":
+            status = Status.ENDED
+        elif event in {"SessionStart", "UserPromptSubmit"}:
+            status = Status.WORKING
+        elif explicit_requires_action is not None:
+            status = Status.WAITING if explicit_requires_action else Status.IDLE
+        elif event == "Notification":
+            status = Status.WAITING if _is_action_required_notification(data) else Status.IDLE
+        elif event == "PreToolUse":
+            # 工具要動了：權限 / 選項類 → 🔴 WAITING；其餘 → 🟢 WORKING。
+            # 非 action 的 PreToolUse 也明確收斂成 WORKING（而非不寫），這樣
+            # 上一個 WAITING（例如剛答完的權限）會被下一個工具動作清掉。
+            status = Status.WAITING if _is_action_required_payload(data) else Status.WORKING
+        elif event == "PostToolUse":
+            # 工具跑完代表使用者已放行、agent 又在動 → 🟢 WORKING。
+            # 這是「回應完」最乾淨的訊號，用來清掉卡住的 WAITING、止住重複通知。
+            status = Status.WORKING
+        if status is None:
+            return None
+        return NormalizedHookEvent(
+            provider=self.provider,
+            event=event,
+            session_id=_qualified_session_id(self.provider, sid),
+            cwd=_first_str(data, "cwd", "current_working_directory", "currentWorkingDirectory"),
+            status=status,
+            transcript_path=_first_str(data, "transcript_path", "transcriptPath", "rollout_path", "rolloutPath"),
+            tty=_first_str(data, "tty"),
+            last_action=_first_str(data, "last_action", "lastAction", "message", "title"),
+            waiting_for=_waiting_for(data),
+        )
+
+
+def adapter_for(provider: str) -> HookAdapter:
+    normalized = normalize_provider(provider)
+    if normalized in {"claude", "claude-code"}:
+        return CommonHookAdapter("claude-code", ("claude",))
+    if normalized == "codex":
+        return CommonHookAdapter("codex", ("codex",))
+    return CommonHookAdapter(normalized or "generic", ())
+
+
+def provider_from_payload(data: Mapping[str, Any], fallback: str = "claude-code") -> str:
+    # 只認明確的 "provider" 欄位。不要拿 "source"——Claude Code 的 SessionStart payload
+    # 帶 source="startup"/"resume"/"clear"/"compact"（觸發來源，不是 provider），
+    # 誤當 provider 會生出 "startup:<id>" 幽靈 session、且永遠不會被標離場。
+    return normalize_provider(_first_str(data, "provider") or fallback)
+
+
+def normalize_provider(provider: str) -> str:
+    return provider.strip().lower().replace("_", "-")
+
+
+def _first_str(data: Mapping[str, Any], *keys: str) -> str:
+    for key in keys:
+        value = data.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return ""
+
+
+def _is_action_required_notification(data: Mapping[str, Any]) -> bool:
+    notification_type = _normalize_token(
+        _first_str(data, "notification_type", "notificationType", "raw_notification_type", "rawNotificationType")
+    )
+    if notification_type in _ACTION_REQUIRED_NOTIFICATION_TYPES:
+        return True
+    return _is_action_required_payload(data)
+
+
+def _explicit_requires_action(data: Mapping[str, Any]) -> bool | None:
+    for key in (
+        "requires_action",
+        "requiresAction",
+        "action_required",
+        "actionRequired",
+        "needs_user_action",
+        "needsUserAction",
+        "requires_input",
+        "requiresInput",
+        "interactive",
+    ):
+        parsed = _parse_bool(data.get(key))
+        if parsed is not None:
+            return parsed
+
+    waiting_for = _waiting_for(data)
+    if not waiting_for:
+        return None
+    if waiting_for in _ACTION_REQUIRED_WAITING_FOR:
+        return True
+    if waiting_for in _IDLE_WAITING_FOR:
+        return False
+    return None
+
+
+def _is_action_required_payload(data: Mapping[str, Any]) -> bool:
+    tool_name = _first_str(data, "tool_name", "toolName", "tool")
+    if tool_name == "AskUserQuestion":
+        return True
+
+    tool_input = data.get("tool_input") or data.get("toolInput") or data.get("input")
+    if isinstance(tool_input, Mapping):
+        questions = tool_input.get("questions")
+        if isinstance(questions, list) and questions:
+            return True
+        options = tool_input.get("options")
+        if isinstance(options, list) and options:
+            return True
+
+    for key in ("questions", "options", "choices"):
+        value = data.get(key)
+        if isinstance(value, list) and value:
+            return True
+    return False
+
+
+def _waiting_for(data: Mapping[str, Any]) -> str:
+    return _normalize_token(
+        _first_str(
+            data,
+            "waiting_for",
+            "waitingFor",
+            "requires",
+            "reason",
+            "interaction",
+            "interaction_type",
+            "interactionType",
+        )
+    ).replace("-", "_")
+
+
+def _parse_bool(value: object) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"1", "true", "yes", "y", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "n", "off"}:
+            return False
+    return None
+
+
+def _normalize_token(value: str) -> str:
+    return value.strip().lower()
+
+
+def _qualified_session_id(provider: str, sid: str) -> str:
+    if ":" in sid:
+        return sid
+    if provider in {"claude", "claude-code"}:
+        return sid
+    return f"{provider}:{sid}"
+
+
+HOOK_EVENTS = (
+    "SessionStart",
+    "UserPromptSubmit",
+    "Notification",
+    "PermissionRequest",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+    "SessionEnd",
+)

ring/i18n.py

@@ -0,0 +1,52 @@
+"""RiNG i18n — gettext。
+
+msgid 用**台灣漢語**：原始碼即預設語言，所以 zh-Hant 不需要任何 ``.mo``。
+其他語言放 ``locale/<lang>/LC_MESSAGES/ring.mo``（由 ``.po`` 編譯，見 README / ``poe i18n-compile``）。
+
+切語言：process 啟動時 ``set_lang()`` 裝上對應 translation；之後 ``_()`` / ``ngettext()`` 就用它。
+在 ``import ring.tui`` 之前先 set_lang，class-level 的 Footer 按鍵說明也會跟著走。
+
+``_()`` 與 ``ngettext()`` 都吃 kwargs：``_("…{x}…", x=1)`` 等同 gettext 後再 ``.format(x=1)``。
+"""
+
+from __future__ import annotations
+
+import gettext as _gettext
+import os
+from pathlib import Path
+
+_LOCALE_DIR = Path(__file__).parent / "locale"
+_DOMAIN = "ring"
+
+_current: _gettext.NullTranslations = _gettext.NullTranslations()
+
+
+def resolve_lang(explicit: str | None = None) -> str:
+    raw = (explicit or os.environ.get("RING_LANG") or os.environ.get("LANG") or "").lower()
+    return "en" if raw.startswith("en") else "zh-Hant"
+
+
+def set_lang(lang: str | None) -> None:
+    """裝上對應語言的 translation。zh-Hant＝msgid 本身（不需 .mo）。"""
+    global _current
+    if resolve_lang(lang) == "zh-Hant":
+        _current = _gettext.NullTranslations()
+        return
+    try:
+        _current = _gettext.translation(_DOMAIN, _LOCALE_DIR, languages=[resolve_lang(lang)])
+    except OSError:  # .mo 不在 → 安靜退回 msgid（中文）
+        _current = _gettext.NullTranslations()
+
+
+def gettext(msgid: str, /, **kw: object) -> str:
+    # msgid 設 positional-only，這樣 format kwarg 取任何名字（msg / n …）都不會撞參數。
+    out = _current.gettext(msgid)
+    return out.format(**kw) if kw else out
+
+
+def ngettext(singular: str, plural: str, count: int, /, **kw: object) -> str:
+    out = _current.ngettext(singular, plural, count)
+    return out.format(**kw) if kw else out
+
+
+_ = gettext

ring/ipc.py

@@ -0,0 +1,220 @@
+"""檔案式 IPC 輔助——RiNG TUI 與 ``ring focus`` subprocess 之間的溝通橋梁。
+
+機制概述
+---------
+- ``~/.config/ring/focus-request``：由 ``ring focus <id>`` 寫入、TUI poll 後讀取並刪除（消費即焚）。
+- ``~/.config/ring/tui-presence``：由 RiNG TUI 啟動時寫入、結束時刪除，同時做「TUI 是否在跑」的判斷依據。
+
+設計原則
+---------
+- 純 stdlib，零新依賴。
+- 所有跨 process 檔案操作包 try/except，失敗安靜吞掉，不打斷 TUI / 通知主流程。
+- ``_config_dir``、``_focus_request_path``、``_presence_path`` 為可在測試中注入的私有常數，
+  使用者透過 ``tmp_path`` 覆寫即可隔離測試環境。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import TypedDict
+
+# --------------------------------------------------------------------------- 路徑常數（可在測試中覆寫）
+
+_CONFIG_DIR: Path = Path.home() / ".config" / "ring"
+_FOCUS_REQUEST_PATH: Path = _CONFIG_DIR / "focus-request"
+_PRESENCE_PATH: Path = _CONFIG_DIR / "tui-presence"
+
+# focus-request 的有效時效（秒）：超過視為 stale，忽略。
+_REQUEST_TTL: float = 30.0
+
+# presence 的有效時效（秒）：超過視為 stale，即使 pid 看起來還活著也不信任。
+_PRESENCE_TTL: float = 300.0
+
+
+# --------------------------------------------------------------------------- 型別
+
+
+class _FocusRequest(TypedDict):
+    session_id: str
+    ts: float
+
+
+class _TuiPresence(TypedDict):
+    tty: str
+    pid: int
+    ts: float
+
+
+# --------------------------------------------------------------------------- focus-request 相關
+
+
+def write_focus_request(session_id: str, *, request_path: Path | None = None) -> None:
+    """把 focus-request 寫入磁碟，供 TUI poll 讀取。
+
+    :param session_id: 要聚焦的 session ID。
+    :param request_path: 可注入路徑（測試用）；省略時用預設路徑。
+    """
+    path = request_path or _FOCUS_REQUEST_PATH
+    payload: _FocusRequest = {"session_id": session_id, "ts": time.time()}
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def read_focus_request(
+    *,
+    request_path: Path | None = None,
+    ttl: float = _REQUEST_TTL,
+) -> str | None:
+    """讀取 focus-request 並消費即焚。
+
+    - 無檔案 → 回傳 ``None``，不刪（無檔可刪）。
+    - 無效 JSON → 刪掉爛檔，回傳 ``None``。
+    - 過期（超過 ttl 秒）→ 刪檔，回傳 ``None``。
+    - 有效 request → 刪檔，回傳 ``session_id``。
+
+    :param request_path: 可注入路徑（測試用）。
+    :param ttl: 有效時效秒數，超過視為 stale。
+    :returns: session_id 或 None。
+    """
+    path = request_path or _FOCUS_REQUEST_PATH
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except Exception:
+        return None
+
+    try:
+        data: _FocusRequest = json.loads(raw)
+        session_id = str(data["session_id"])
+        ts = float(data["ts"])
+    except Exception:
+        # 解析失敗：刪掉爛檔
+        try:
+            path.unlink()
+        except Exception:
+            pass
+        return None
+
+    age = time.time() - ts
+    # 不論有效或過期，都刪掉（消費即焚；過期的也不留）
+    try:
+        path.unlink()
+    except Exception:
+        pass
+
+    if age > ttl:
+        return None
+
+    return session_id
+
+
+# --------------------------------------------------------------------------- tui-presence 相關
+
+
+def _pid_alive(pid: int) -> bool:
+    """檢查 pid 是否仍存活（送 signal 0）。"""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError):
+        return False
+    except Exception:
+        return False
+
+
+def write_tui_presence(*, presence_path: Path | None = None) -> None:
+    """將目前 process 的 tty / pid / ts 寫入 presence 檔。
+
+    tty 取自 controlling terminal（``os.ttyname(sys.stdout.fileno())`` 或類似）。
+    若無法取得 tty（非互動終端）則寫空字串，讓 activate 步驟跳過而不崩。
+
+    :param presence_path: 可注入路徑（測試用）。
+    """
+    path = presence_path or _PRESENCE_PATH
+    tty = ""
+    try:
+        # 優先用 stdout；若 stdout 非 tty，嘗試直接開 /dev/tty
+        if sys.stdout.isatty():
+            tty = os.ttyname(sys.stdout.fileno())
+        else:
+            fd = os.open("/dev/tty", os.O_RDONLY | os.O_NOCTTY)
+            try:
+                tty = os.ttyname(fd)
+            finally:
+                os.close(fd)
+    except Exception:
+        pass  # headless / no controlling terminal，tty 留空字串
+
+    payload: _TuiPresence = {"tty": tty, "pid": os.getpid(), "ts": time.time()}
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def read_tui_presence(
+    *,
+    presence_path: Path | None = None,
+    ttl: float = _PRESENCE_TTL,
+) -> _TuiPresence | None:
+    """讀取 presence 檔，判斷 TUI 是否確實在跑。
+
+    判定規則：
+    - 無檔案、無效 JSON → ``None``。
+    - ts 超過 ttl → stale，刪檔並回傳 ``None``。
+    - pid 已死 → stale，刪檔並回傳 ``None``。
+    - 以上均通過 → 回傳 presence dict。
+
+    :param presence_path: 可注入路徑（測試用）。
+    :param ttl: 有效時效秒數。
+    :returns: ``_TuiPresence`` 或 ``None``。
+    """
+    path = presence_path or _PRESENCE_PATH
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except Exception:
+        return None
+
+    try:
+        data: _TuiPresence = json.loads(raw)
+        tty = str(data.get("tty", ""))
+        pid = int(data["pid"])
+        ts = float(data["ts"])
+    except Exception:
+        return None
+
+    age = time.time() - ts
+    if age > ttl:
+        try:
+            path.unlink()
+        except Exception:
+            pass
+        return None
+
+    if not _pid_alive(pid):
+        try:
+            path.unlink()
+        except Exception:
+            pass
+        return None
+
+    return _TuiPresence(tty=tty, pid=pid, ts=ts)
+
+
+def clear_tui_presence(*, presence_path: Path | None = None) -> None:
+    """刪除 presence 檔（TUI 離場時呼叫）。
+
+    :param presence_path: 可注入路徑（測試用）。
+    """
+    path = presence_path or _PRESENCE_PATH
+    try:
+        path.unlink()
+    except Exception:
+        pass

ring/labels.py

@@ -0,0 +1,50 @@
+"""Session 自訂標籤——本機持久化「這個 session 是什麼」。
+
+存在 ``~/.config/ring/labels.json``：``{session_id: label}``。純 stdlib，所有檔案操作
+失敗一律安靜吞掉（標籤是錦上添花，不該打斷 TUI / 快照主流程）。``_LABELS_PATH`` 可在
+測試中以 ``path=`` 參數覆寫隔離。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_LABELS_PATH: Path = Path.home() / ".config" / "ring" / "labels.json"
+
+
+def load_labels(*, path: Path | None = None) -> dict[str, str]:
+    """讀整份標籤表；缺檔 / 壞檔 / 型別不符一律回空 dict。"""
+    p = path or _LABELS_PATH
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {str(k): v for k, v in data.items() if isinstance(v, str) and v}
+
+
+def get_label(session_id: str, *, path: Path | None = None) -> str:
+    """取單一 session 的標籤；沒有就回空字串。"""
+    return load_labels(path=path).get(session_id, "")
+
+
+def set_label(session_id: str, label: str, *, path: Path | None = None) -> None:
+    """設定 / 更新某 session 的標籤；傳空字串（或全空白）則移除該標籤。"""
+    p = path or _LABELS_PATH
+    labels = load_labels(path=path)
+    label = label.strip()
+    if label:
+        labels[session_id] = label
+    elif session_id not in labels:
+        return  # 本來就沒有，且要清空 → 不必寫檔
+    else:
+        labels.pop(session_id, None)
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(labels, ensure_ascii=False), encoding="utf-8")
+        tmp.replace(p)  # atomic
+    except Exception:
+        pass