ring-cli 0.14.0__tar.gz → 0.14.1__tar.gz

{ring_cli-0.14.0 → ring_cli-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.14.0
+Version: 0.14.1
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,ollama,llama-cpp,tui,dashboard,session,monitor,rich
 Author: Wei Lee

{ring_cli-0.14.0 → ring_cli-0.14.1}/pyproject.toml

@@ -2,7 +2,7 @@
 # import 的 module（見 [tool.uv.build-backend] module-name）與 CLI 指令仍是 `ring`。
 [project]
 name = "ring-cli"
-version = "0.14.0"
+version = "0.14.1"
 description = "RiNG — Realtime Instance Notification Grid for active agent CLI sessions."
 readme = "README.en.md"
 requires-python = ">=3.13"

{ring_cli-0.14.0 → ring_cli-0.14.1}/src/ring/focus/__init__.py

@@ -15,6 +15,7 @@ from ring.focus.linux_wm import focuser as _linux_wm
 from ring.focus.neovim import focuser as _neovim
 from ring.focus.terminal import focuser as _terminal
 from ring.focus.tmux import focuser as _tmux
+from ring.focus.trace import log_jump
 from ring.i18n import gettext as _
 from ring.registry import Session, Status
 
@@ -53,33 +54,53 @@ def focusers() -> list[Focuser]:
 
 
 def jump(session: Session) -> tuple[bool, str]:
-    """依序問每個 focuser，誰先接手就用誰。回傳 (成功?, 訊息)。"""
+    """依序問每個 focuser，誰先接手就用誰。回傳 (成功?, 訊息)。
+
+    每次跳轉（不論成敗）都記一行到 focus.jsonl，供事後歸因間歇性的跳不過去（見 ``trace``）。
+    """
     if session.status is Status.ENDED:
         return False, _("已離場的 session 無法跳轉")
     failures: list[str] = []
     preparations: list[str] = []
+    attempts: list[tuple[str, str]] = []
+
+    def _done(ok: bool, msg: str) -> tuple[bool, str]:
+        log_jump(
+            session_id=session.session_id,
+            provider=session.provider,
+            tty=session.tty or "",
+            tmux_target=session.tmux_target or "",
+            attempts=attempts,
+            ok=ok,
+            msg=msg,
+        )
+        return ok, msg
+
     for focuser in _FOCUSERS:
         result = focuser.try_focus(session)
         if result is None:
+            attempts.append((focuser.name, "skip"))
             continue
         ok, msg = result
         if ok:
+            attempts.append((focuser.name, "ok"))
             if getattr(focuser, "continue_after_success", False):
                 preparations.append(msg)
                 continue
             if preparations:
-                return True, "; ".join([*preparations, msg])
-            return True, msg
+                return _done(True, "; ".join([*preparations, msg]))
+            return _done(True, msg)
+        attempts.append((focuser.name, f"fail: {msg}"))
         failures.append(f"{focuser.name}: {msg}")
     if preparations and failures:
-        return False, "; ".join([*preparations, *failures])
+        return _done(False, "; ".join([*preparations, *failures]))
     if preparations:
-        return True, "; ".join(preparations)
+        return _done(True, "; ".join(preparations))
     if failures:
-        return False, "; ".join(failures)
+        return _done(False, "; ".join(failures))
     if session.tty:
-        return False, _("找不到這個終端分頁（可能已關閉；刷新後若仍存在，請裝 hook 取得更精準狀態）")
-    return False, _("沒有 focuser 接得住（裝 hook，或一個專案只開一個 session 才測得到 tty）")
+        return _done(False, _("找不到這個終端分頁（可能已關閉；刷新後若仍存在，請裝 hook 取得更精準狀態）"))
+    return _done(False, _("沒有 focuser 接得住（裝 hook，或一個專案只開一個 session 才測得到 tty）"))
 
 
 __all__ = ["Focuser", "focusers", "jump", "register_focuser"]

{ring_cli-0.14.0 → ring_cli-0.14.1}/src/ring/focus/applescript.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import shutil
 
+from ring.i18n import gettext as _
 from ring.osascript import osascript
 from ring.registry import Session
 
@@ -16,6 +17,9 @@ class AppleScriptTTYFocuser:
     """用 session 的 tty 在某個 macOS 終端 app 裡找到對應分頁並聚焦。
 
     各 app 提供自己的 AppleScript（用 ``is running`` 守衛，沒在跑的 app 不會被喚醒）。
+
+    script 的回傳值三選一：``ok``（找到且已在前景）、``notfound``（不歸這個 app 管）、
+    ``unraised``（找到分頁但視窗沒浮到前景——腳本自己驗過才回這個，見 iterm2 模組）。
     """
 
     def __init__(self, app: str, script: str) -> None:
@@ -31,4 +35,8 @@ class AppleScriptTTYFocuser:
             return True, f"{self.name} {tty}"
         if rc == 0 and out == "notfound":
             return None  # 這個 app 沒有這個 tty → 換下一個 focuser
+        if rc == 0 and out == "unraised":
+            # 分頁在，但視窗沒被帶到前景（多半在別的 Space 或全螢幕）。照實回失敗，
+            # 不要讓 TUI 顯示「跳過去了」卻什麼都沒發生。
+            return False, _("{app} 找到分頁了，但視窗沒浮到前景（可能在別的 Space 或全螢幕）", app=self.name)
         return False, err or out or f"returncode={rc}"

ring_cli-0.14.1/src/ring/focus/iterm2.py

@@ -0,0 +1,82 @@
+"""iTerm2 focuser（macOS）：用 tty 找到對應分頁並帶到前景。
+
+跨視窗（不是同一視窗換分頁）跳轉踩過三個坑，腳本的形狀都是為了繞開它們（皆 2026-07-25 實測）：
+
+1. **位置型 specifier 會在迴圈中途失效**。``repeat with w in windows`` 的迴圈變數其實是
+   ``item M of every window`` 這種「按位置」的參照；一旦 windows 的順序在掃描途中變動
+   （剛跳過一次視窗、使用者手動點了別的視窗都會），下一次取值就噴
+   ``Invalid index (-1719)``，跳轉整個失敗——這正是「不同視窗有時抓不到」的主因。
+   對策：掃描包在 ``try`` 裡、順序被動到就重掃；``select`` 之後不再用掃描時的位置，
+   改以 ``current window`` 為根重找一次分頁。
+2. **``select`` 是非同步的**：送出後立刻讀狀態會讀到舊值。所以最後隔 0.1 秒回頭驗
+   ``current session of current window``，最多等 1 秒。驗不到就回 ``unraised``，讓上層
+   照實說「沒帶到前景」（例如視窗在別的 Space），而不是假裝跳成功。
+3. **不能用的兩招**：``set frontmost of w to true``（Terminal.app 那招）在 iTerm2 噴
+   AppleEvent handler failed (-10000)；``set index of w to 1`` 會主動重排 windows，
+   等於自己製造第 1 點的 -1719。
+
+縮到 Dock 的視窗 ``select`` 就叫得回來（實測），``miniaturized`` 那段只是保險。
+"""
+
+from __future__ import annotations
+
+from ring.focus.applescript import AppleScriptTTYFocuser
+
+_SCRIPT = """
+if application "iTerm2" is running then
+  tell application "iTerm2"
+    repeat 3 times
+      try
+        set wIdx to 0
+        set tIdx to 0
+        set sIdx to 0
+        repeat with wi from 1 to (count of windows)
+          repeat with ti from 1 to (count of tabs of window wi)
+            repeat with si from 1 to (count of sessions of tab ti of window wi)
+              if tty of session si of tab ti of window wi is "{tty}" then
+                set wIdx to wi
+                set tIdx to ti
+                set sIdx to si
+                exit repeat
+              end if
+            end repeat
+            if wIdx is not 0 then exit repeat
+          end repeat
+          if wIdx is not 0 then exit repeat
+        end repeat
+        if wIdx is 0 then return "notfound"
+        activate
+        try
+          if miniaturized of window wIdx then set miniaturized of window wIdx to false
+        end try
+        select window wIdx
+        tell current window
+          repeat with ti2 from 1 to (count of tabs)
+            repeat with si2 from 1 to (count of sessions of tab ti2)
+              if tty of session si2 of tab ti2 is "{tty}" then
+                select tab ti2
+                select session si2 of tab ti2
+                exit repeat
+              end if
+            end repeat
+          end repeat
+        end tell
+        repeat 10 times
+          delay 0.1
+          try
+            if tty of current session of current window is "{tty}" then return "ok"
+          end try
+        end repeat
+        return "unraised"
+      on error number errNum
+        if errNum is -128 then error number -128
+        delay 0.2
+      end try
+    end repeat
+    return "unraised"
+  end tell
+end if
+return "notfound"
+"""
+
+focuser = AppleScriptTTYFocuser("iTerm2", _SCRIPT)

ring_cli-0.14.1/src/ring/focus/trace.py

@@ -0,0 +1,79 @@
+"""跳轉取證 log——每次 ``jump()`` append 一行到 ``~/.config/ring/focus.jsonl``。
+
+為什麼要記：跳轉失敗是間歇性的，而 TUI 的 toast 看過就沒了，事後只剩「昨天有一次跳不
+過去」這種無法歸因的敘述。這份 log 把每個 focuser 當下的回覆存下來，讓下一次重現時能
+直接分辨是哪一種失敗：
+
+- 每個 focuser 都回 ``skip``、而 session 有 tty → tty 已失效（分頁關了／registry 記的是舊的）
+- ``tty`` 是空的 → 根本沒抓到 tty，focuser 沒得比對
+- iTerm2 回 ``unraised`` → 分頁找到了但視窗沒浮上來（多半在別的 Space）
+- iTerm2 回 osascript 錯誤 → 權限或 5 秒 timeout
+
+跳轉是使用者手動觸發、頻率低（一行約 200 bytes），所以預設就開著、不做開關——要能在
+「下次發生」時就有證據，而不是先想起來去開 debug 旗標。寫入失敗一律安靜吞掉。
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+FOCUS_LOG_PATH = Path.home() / ".config" / "ring" / "focus.jsonl"
+
+# 一行約 200 bytes，1MB ≈ 5000 次跳轉。超過就砍半保新。
+_MAX_BYTES = 1024 * 1024
+
+
+def log_jump(
+    *,
+    session_id: str,
+    provider: str,
+    tty: str,
+    tmux_target: str,
+    attempts: list[tuple[str, str]],
+    ok: bool,
+    msg: str,
+    path: Path | None = None,
+    now: float | None = None,
+) -> None:
+    """append 一次跳轉的完整經過；失敗安靜吞掉（呼叫端不需要自己包 try）。
+
+    :param attempts: ``[(focuser 名稱, 結果), …]``，結果為 ``skip`` / ``ok`` / ``fail: …``。
+    """
+    p = path or FOCUS_LOG_PATH
+    try:
+        line = json.dumps(
+            {
+                "ts": now if now is not None else time.time(),
+                "session_id": session_id,
+                "provider": provider,
+                "tty": tty,
+                "tmux_target": tmux_target,
+                "attempts": [{"focuser": name, "result": result} for name, result in attempts],
+                "ok": ok,
+                "msg": msg,
+            },
+            ensure_ascii=False,
+            default=str,
+        )
+        p.parent.mkdir(parents=True, exist_ok=True)
+        _trim_if_oversized(p)
+        with p.open("a", encoding="utf-8") as f:
+            f.write(line + "\n")
+    except Exception:
+        pass
+
+
+def _trim_if_oversized(p: Path) -> None:
+    """log 超過 ``_MAX_BYTES`` 時砍半保新，避免無上限成長。失敗安靜放棄（不擋 append）。"""
+    try:
+        if p.stat().st_size <= _MAX_BYTES:
+            return
+        lines = p.read_text(encoding="utf-8").splitlines()
+        keep = lines[len(lines) // 2 :]
+        tmp = p.with_suffix(".jsonl.tmp")
+        tmp.write_text("\n".join(keep) + "\n", encoding="utf-8")
+        tmp.replace(p)  # atomic
+    except Exception:
+        pass

{ring_cli-0.14.0 → ring_cli-0.14.1}/src/ring/locale/en/LC_MESSAGES/ring.po

@@ -155,6 +155,9 @@ msgstr "Hidden {project} (no RiNG registry to clear; it reappears once there's n
 msgid "已離場的 session 無法跳轉"
 msgstr "ended sessions cannot be focused"
 
+msgid "{app} 找到分頁了，但視窗沒浮到前景（可能在別的 Space 或全螢幕）"
+msgstr "{app} found the tab but could not bring its window to the front (it may be on another Space or in full screen)"
+
 msgid "找不到這個終端分頁（可能已關閉；刷新後若仍存在，請裝 hook 取得更精準狀態）"
 msgstr "terminal tab not found (it may have been closed; if it still appears after refresh, install hooks for more precise state)"
 

{ring_cli-0.14.0 → ring_cli-0.14.1}/src/ring/locale/ring.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PROJECT VERSION\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2026-07-20 15:34+0800\n"
+"POT-Creation-Date: 2026-07-25 10:42+0800\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -923,18 +923,23 @@ msgstr ""
 msgid "⚠️ 其中 {n} 段還在 🔴 等你（計到現在為止）。"
 msgstr ""
 
-#: src/ring/focus/__init__.py:58
+#: src/ring/focus/__init__.py:62
 msgid "已離場的 session 無法跳轉"
 msgstr ""
 
-#: src/ring/focus/__init__.py:81
+#: src/ring/focus/__init__.py:102
 msgid "找不到這個終端分頁（可能已關閉；刷新後若仍存在，請裝 hook 取得更精準狀態）"
 msgstr ""
 
-#: src/ring/focus/__init__.py:82
+#: src/ring/focus/__init__.py:103
 msgid "沒有 focuser 接得住（裝 hook，或一個專案只開一個 session 才測得到 tty）"
 msgstr ""
 
+#: src/ring/focus/applescript.py:41
+#, python-brace-format
+msgid "{app} 找到分頁了，但視窗沒浮到前景（可能在別的 Space 或全螢幕）"
+msgstr ""
+
 #: src/ring/notify/__init__.py:165
 #, python-brace-format
 msgid "另有 {n} 個 session 在等你"

ring_cli-0.14.0/src/ring/focus/iterm2.py

@@ -1,28 +0,0 @@
-"""iTerm2 focuser（macOS）：用 tty 找到對應分頁並帶到前景。"""
-
-from __future__ import annotations
-
-from ring.focus.applescript import AppleScriptTTYFocuser
-
-_SCRIPT = """
-if application "iTerm2" is running then
-  tell application "iTerm2"
-    repeat with w in windows
-      repeat with t in tabs of w
-        repeat with s in sessions of t
-          if tty of s is "{tty}" then
-            select w
-            select t
-            select s
-            activate
-            return "ok"
-          end if
-        end repeat
-      end repeat
-    end repeat
-  end tell
-end if
-return "notfound"
-"""
-
-focuser = AppleScriptTTYFocuser("iTerm2", _SCRIPT)