ring-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{ring_cli-0.6.0 → ring_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -162,6 +162,7 @@ Completes subcommands, flags, and `config set` keys.
 Select a session and press `Enter`. RiNG focuses the terminal where that session is running.
 
 - **tmux**: switches directly to the pane via `switch-client`.
+- **Neovim `:terminal`**: uses the terminal job's inherited `$NVIM` server socket to switch to the exact buffer, then lets the outer tmux or terminal focuser raise its pane/window.
 - **iTerm2 / Terminal.app** on macOS: uses the session `tty` and AppleScript to focus the matching tab. The first run may ask for macOS Automation permission.
 - **Linux X11 window** (`wmctrl`, best-effort fallback): for Linux without tmux — walks from the `tty` up to the terminal window that owns it and raises it via `wmctrl`. **Limits**: X11 only (usually a no-op on Wayland), raises the whole window but cannot pick the tab, and gnome-terminal's client/server model may not match. Requires `apt install wmctrl`.
 
@@ -371,7 +372,7 @@ notify_repeat_max = 3
 notify_ntfy_url = ""             # full ntfy topic URL enables phone push (e.g. https://ntfy.sh/my-topic)
 notify_webhook_url = ""          # URL enables the generic webhook backend (JSON POST)
 notify_also = []                 # extra backends fired besides the primary, e.g. ["ntfy"]
-focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]
+focusers = ["Neovim", "tmux", "iTerm2", "Terminal", "linux-wm"]
 plugins = []                     # external plugin modules imported at startup (see Extending)
 
 [colors]

{ring_cli-0.6.0 → ring_cli-0.7.0}/README.en.md

@@ -137,6 +137,7 @@ Completes subcommands, flags, and `config set` keys.
 Select a session and press `Enter`. RiNG focuses the terminal where that session is running.
 
 - **tmux**: switches directly to the pane via `switch-client`.
+- **Neovim `:terminal`**: uses the terminal job's inherited `$NVIM` server socket to switch to the exact buffer, then lets the outer tmux or terminal focuser raise its pane/window.
 - **iTerm2 / Terminal.app** on macOS: uses the session `tty` and AppleScript to focus the matching tab. The first run may ask for macOS Automation permission.
 - **Linux X11 window** (`wmctrl`, best-effort fallback): for Linux without tmux — walks from the `tty` up to the terminal window that owns it and raises it via `wmctrl`. **Limits**: X11 only (usually a no-op on Wayland), raises the whole window but cannot pick the tab, and gnome-terminal's client/server model may not match. Requires `apt install wmctrl`.
 
@@ -346,7 +347,7 @@ notify_repeat_max = 3
 notify_ntfy_url = ""             # full ntfy topic URL enables phone push (e.g. https://ntfy.sh/my-topic)
 notify_webhook_url = ""          # URL enables the generic webhook backend (JSON POST)
 notify_also = []                 # extra backends fired besides the primary, e.g. ["ntfy"]
-focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]
+focusers = ["Neovim", "tmux", "iTerm2", "Terminal", "linux-wm"]
 plugins = []                     # external plugin modules imported at startup (see Extending)
 
 [colors]

{ring_cli-0.6.0 → ring_cli-0.7.0}/pyproject.toml

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

{ring_cli-0.6.0 → ring_cli-0.7.0}/src/ring/commands/doctor.py

@@ -87,7 +87,10 @@ def run_doctor(args: list[str]) -> int:
     width_f = max(len(f.name) for f in focuser_list) if focuser_list else 10
     for f in focuser_list:
         name_lower = f.name.lower()
-        if name_lower == "tmux":
+        if name_lower == "neovim":
+            avail = shutil.which("nvim") is not None
+            avail_str = _("可用") if avail else _("不可用（nvim 不在 PATH）")
+        elif name_lower == "tmux":
             avail = shutil.which("tmux") is not None
             avail_str = _("可用") if avail else _("不可用（tmux 不在 PATH）")
         elif shutil.which("osascript") is None:

{ring_cli-0.6.0 → ring_cli-0.7.0}/src/ring/config.py

@@ -23,7 +23,7 @@
     notify_ntfy_url = "https://ntfy.sh/my-topic"   # 設了才啟用 ntfy 後端（推到手機）
     notify_webhook_url = "https://example.com/hook"  # 設了才啟用 webhook 後端（JSON POST）
     notify_also = ["ntfy"]            # 主後端之外「加發」的後端（例如桌面通知＋手機各一份）
-    focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]  # 跳轉嘗試順序；省略＝內建預設
+    focusers = ["Neovim", "tmux", "iTerm2", "Terminal", "linux-wm"]  # 跳轉嘗試順序；省略＝內建預設
     plugins = ["my_ring_plugin"]      # 啟動時 import 的外部 plugin 模組（自行 register_*）
 """
 

{ring_cli-0.6.0 → ring_cli-0.7.0}/src/ring/focus/__init__.py

@@ -2,8 +2,8 @@
 
 每個終端是一個 ``Focuser``（見 ``base.Focuser``）：core 不認識任何具體終端，
 只依序問每個 focuser「這個 session 歸不歸你管」。要支援新終端＝寫一個模組、
-``register_focuser()`` 註冊，core 零改動。內建：tmux / iTerm2 / Terminal.app /
-Linux X11 視窗（wmctrl，best-effort fallback）。
+``register_focuser()`` 註冊，core 零改動。內建：Neovim terminal / tmux / iTerm2 /
+Terminal.app / Linux X11 視窗（wmctrl，best-effort fallback）。
 """
 
 from __future__ import annotations
@@ -12,14 +12,16 @@ from ring.config import get_config
 from ring.focus.base import Focuser
 from ring.focus.iterm2 import focuser as _iterm2
 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.i18n import gettext as _
 from ring.registry import Session, Status
 
-# 內建 focuser。順序可由 config 的 `focusers` 覆寫。tmux 跨平台、最快，排最前；
-# macOS app 在非 macOS 會自己 return None；linux-wm 殿後當 X11 fallback。
+# 內建 focuser。順序可由 config 的 `focusers` 覆寫。Neovim 先切內層 terminal buffer，
+# 再由 tmux / macOS app / linux-wm 把外層帶到前景。
 _BUILTIN: dict[str, Focuser] = {
+    "Neovim": _neovim,
     "tmux": _tmux,
     "iTerm2": _iterm2,
     "Terminal": _terminal,
@@ -55,14 +57,24 @@ def jump(session: Session) -> tuple[bool, str]:
     if session.status is Status.ENDED:
         return False, _("已離場的 session 無法跳轉")
     failures: list[str] = []
+    preparations: list[str] = []
     for focuser in _FOCUSERS:
         result = focuser.try_focus(session)
         if result is None:
             continue
         ok, msg = result
         if ok:
+            if getattr(focuser, "continue_after_success", False):
+                preparations.append(msg)
+                continue
+            if preparations:
+                return True, "; ".join([*preparations, msg])
             return True, msg
         failures.append(f"{focuser.name}: {msg}")
+    if preparations and failures:
+        return False, "; ".join([*preparations, *failures])
+    if preparations:
+        return True, "; ".join(preparations)
     if failures:
         return False, "; ".join(failures)
     if session.tty:

{ring_cli-0.6.0 → ring_cli-0.7.0}/src/ring/focus/base.py

@@ -3,7 +3,10 @@
 ``try_focus`` 的回傳語意：
   None          → 不歸我管（dispatcher 換下一個）
   (True, msg)   → 我接手且成功
-  (False, err)  → 我接手但失敗（回報原因，不再往下試）
+  (False, err)  → 我接手但失敗（記下原因，再試其他 focuser）
+
+一般 focuser 成功後 dispatcher 就停止；需要先處理內層、再交給外層 focuser 的實作可設
+``continue_after_success = True``（例如 Neovim 先切 terminal buffer，再讓 tmux 聚焦 pane）。
 """
 
 from __future__ import annotations

ring_cli-0.7.0/src/ring/focus/neovim.py

@@ -0,0 +1,184 @@
+"""Neovim terminal focuser：切回承載 session 的 ``:terminal`` buffer。
+
+Neovim 的 terminal job 會繼承 ``NVIM``（server socket）環境變數。從 session 的 tty
+找到該 job，再沿 parent process chain 找到 owning nvim，就能透過 remote API 精準切換
+buffer。這個 focuser 是「前置聚焦」：切完內層 buffer 後，dispatcher 仍會繼續讓 tmux /
+iTerm2 / Terminal.app 把外層 pane 或視窗帶到前景。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from shutil import which
+
+from ring.registry import Session
+
+_NVIM_NAMES = {"nvim", "nvim-bin"}
+_NVIM_ENV_RE = re.compile(r"(?:^|\s)NVIM=([^\s]+)")
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess[str] | None:
+    try:
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=3)
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _tty_pids(tty: str) -> list[int]:
+    result = _run(["ps", "-o", "pid=", "-t", tty.removeprefix("/dev/")])
+    if result is None or result.returncode != 0:
+        return []
+    pids: list[int] = []
+    for value in result.stdout.split():
+        try:
+            pids.append(int(value))
+        except ValueError:
+            continue
+    return pids
+
+
+def _process_table() -> tuple[dict[int, int], dict[int, str]]:
+    result = _run(["ps", "-eo", "pid=,ppid=,comm="])
+    if result is None or result.returncode != 0:
+        return {}, {}
+    parents: dict[int, int] = {}
+    commands: dict[int, str] = {}
+    for line in result.stdout.splitlines():
+        parts = line.split(None, 2)
+        if len(parts) != 3:
+            continue
+        try:
+            pid, ppid = int(parts[0]), int(parts[1])
+        except ValueError:
+            continue
+        parents[pid] = ppid
+        commands[pid] = os.path.basename(parts[2])
+    return parents, commands
+
+
+def _ancestors(pid: int, parents: dict[int, int]) -> list[int]:
+    chain: list[int] = []
+    seen: set[int] = set()
+    current = pid
+    while current > 1 and current not in seen:
+        seen.add(current)
+        chain.append(current)
+        current = parents.get(current, 0)
+    return chain
+
+
+def _nvim_address(pid: int) -> str:
+    """讀 process 繼承到的 ``NVIM``；Linux 優先用不會混入 argv 的 procfs。"""
+    if sys.platform.startswith("linux"):
+        try:
+            entries = Path(f"/proc/{pid}/environ").read_bytes().split(b"\0")
+        except OSError:
+            entries = []
+        for entry in entries:
+            if entry.startswith(b"NVIM="):
+                return entry.removeprefix(b"NVIM=").decode(errors="surrogateescape")
+
+    result = _run(["ps", "eww", "-p", str(pid), "-o", "command="])
+    if result is None or result.returncode != 0:
+        return ""
+    match = _NVIM_ENV_RE.search(result.stdout)
+    return match.group(1) if match else ""
+
+
+def _pid_tty(pid: int) -> str:
+    result = _run(["ps", "-o", "tty=", "-p", str(pid)])
+    if result is None or result.returncode != 0:
+        return ""
+    tty = result.stdout.strip()
+    if not tty or tty in {"?", "??"}:
+        return ""
+    return tty if tty.startswith("/dev/") else f"/dev/{tty}"
+
+
+def _find_neovim(tty: str) -> tuple[str, int] | None:
+    parents, commands = _process_table()
+    for pid in _tty_pids(tty):
+        address = _nvim_address(pid)
+        if not address:
+            continue
+        for ancestor in _ancestors(pid, parents):
+            if commands.get(ancestor) in _NVIM_NAMES:
+                return address, ancestor
+    return None
+
+
+def _remote_expr(tty: str) -> str:
+    """建立在 server 端找 terminal job tty、切 tab/window/buffer 的 Lua expression。"""
+    target = json.dumps(tty)
+    lua = f"""(function()
+  local target = {target}
+  local function job_tty(pid)
+    local value = vim.trim(vim.fn.system({{'ps', '-o', 'tty=', '-p', tostring(pid)}}))
+    if value == '' or value == '?' or value == '??' then return '' end
+    if vim.startswith(value, '/dev/') then return value end
+    return '/dev/' .. value
+  end
+  for _, buf in ipairs(vim.api.nvim_list_bufs()) do
+    local ok, job = pcall(vim.api.nvim_buf_get_var, buf, 'terminal_job_id')
+    -- 已死的 :terminal buffer（[Process exited]）還留著 terminal_job_id，但 channel
+    -- 已關，jobpid 會丟 E900——pcall 跳過它，才輪得到後面活著的 buffer。
+    local ok_pid, pid = pcall(vim.fn.jobpid, job)
+    if ok and ok_pid and job_tty(pid) == target then
+      for _, tab in ipairs(vim.api.nvim_list_tabpages()) do
+        for _, win in ipairs(vim.api.nvim_tabpage_list_wins(tab)) do
+          if vim.api.nvim_win_get_buf(win) == buf then
+            vim.api.nvim_set_current_tabpage(tab)
+            vim.api.nvim_set_current_win(win)
+            vim.cmd('startinsert')
+            return buf
+          end
+        end
+      end
+      vim.api.nvim_set_current_buf(buf)
+      vim.cmd('startinsert')
+      return buf
+    end
+  end
+  return 0
+end)()"""
+    return f"luaeval({json.dumps(lua)})"
+
+
+class NeovimFocuser:
+    name = "Neovim"
+    continue_after_success = True
+
+    def try_focus(self, session: Session) -> tuple[bool, str] | None:
+        tty = session.tty
+        nvim = which("nvim")
+        if not tty or not nvim:
+            return None
+        found = _find_neovim(tty)
+        if found is None:
+            return None
+        address, nvim_pid = found
+        result = _run([nvim, "--server", address, "--remote-expr", _remote_expr(tty)])
+        if result is None:
+            return False, "nvim remote request failed"
+        if result.returncode != 0:
+            return False, result.stderr.strip() or "nvim remote request failed"
+        try:
+            buffer = int(result.stdout.strip())
+        except ValueError:
+            buffer = 0
+        if buffer <= 0:
+            return False, f"terminal buffer for {tty} not found"
+
+        # 後續外層 focuser 要比對 nvim 自己所在的 tty，而不是內層 :terminal job 的 tty。
+        outer_tty = _pid_tty(nvim_pid)
+        if outer_tty:
+            session.tty = outer_tty
+        return True, f"Neovim buffer {buffer}"
+
+
+focuser = NeovimFocuser()

{ring_cli-0.6.0 → ring_cli-0.7.0}/src/ring/locale/en/LC_MESSAGES/ring.po

@@ -382,6 +382,9 @@ msgstr "all unavailable"
 msgid "聚焦終端（focuser）"
 msgstr "Terminal Focuser"
 
+msgid "不可用（nvim 不在 PATH）"
+msgstr "unavailable (nvim not in PATH)"
+
 msgid "不可用（tmux 不在 PATH）"
 msgstr "unavailable (tmux not in PATH)"
 

{ring_cli-0.6.0 → ring_cli-0.7.0}/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-03 00:39+0800\n"
+"POT-Creation-Date: 2026-07-03 08:44+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"
@@ -61,7 +61,7 @@ msgid "（場館目前沒人上台）"
 msgstr ""
 
 #: src/ring/cli.py:178 src/ring/cli.py:326 src/ring/commands/doctor.py:31
-#: src/ring/commands/doctor.py:119 src/ring/tui.py:163
+#: src/ring/commands/doctor.py:122 src/ring/tui.py:163
 msgid "狀態"
 msgstr ""
 
@@ -98,15 +98,15 @@ msgstr ""
 msgid "RiNG 設定檔"
 msgstr ""
 
-#: src/ring/cli.py:325 src/ring/commands/doctor.py:118
+#: src/ring/cli.py:325 src/ring/commands/doctor.py:121
 msgid "路徑"
 msgstr ""
 
-#: src/ring/cli.py:326 src/ring/commands/doctor.py:119
+#: src/ring/cli.py:326 src/ring/commands/doctor.py:122
 msgid "已存在"
 msgstr ""
 
-#: src/ring/cli.py:326 src/ring/commands/doctor.py:119
+#: src/ring/cli.py:326 src/ring/commands/doctor.py:122
 msgid "不存在（全部用內建預設）"
 msgstr ""
 
@@ -434,7 +434,7 @@ msgstr ""
 msgid "偵測到 {n} 個 session"
 msgstr ""
 
-#: src/ring/commands/doctor.py:45 src/ring/commands/doctor.py:113
+#: src/ring/commands/doctor.py:45 src/ring/commands/doctor.py:116
 msgid "偵測失敗"
 msgstr ""
 
@@ -463,7 +463,7 @@ msgid "目前設定"
 msgstr ""
 
 #: src/ring/commands/doctor.py:68 src/ring/commands/doctor.py:92
-#: src/ring/commands/doctor.py:99
+#: src/ring/commands/doctor.py:95 src/ring/commands/doctor.py:102
 msgid "可用"
 msgstr ""
 
@@ -500,40 +500,44 @@ msgid "聚焦終端（focuser）"
 msgstr ""
 
 #: src/ring/commands/doctor.py:92
+msgid "不可用（nvim 不在 PATH）"
+msgstr ""
+
+#: src/ring/commands/doctor.py:95
 msgid "不可用（tmux 不在 PATH）"
 msgstr ""
 
-#: src/ring/commands/doctor.py:94
+#: src/ring/commands/doctor.py:97
 msgid "不可用（osascript 不在 PATH）"
 msgstr ""
 
-#: src/ring/commands/doctor.py:99 src/ring/commands/doctor.py:101
+#: src/ring/commands/doctor.py:102 src/ring/commands/doctor.py:104
 msgid "不可用（app 沒在跑）"
 msgstr ""
 
-#: src/ring/commands/doctor.py:105
+#: src/ring/commands/doctor.py:108
 msgid "維護"
 msgstr ""
 
-#: src/ring/commands/doctor.py:109 src/ring/commands/doctor.py:111
-#: src/ring/commands/doctor.py:113
+#: src/ring/commands/doctor.py:112 src/ring/commands/doctor.py:114
+#: src/ring/commands/doctor.py:116
 msgid "可清理"
 msgstr ""
 
-#: src/ring/commands/doctor.py:109
+#: src/ring/commands/doctor.py:112
 #, python-brace-format
 msgid "{n} 個 RiNG stale 狀態檔（執行 ring gc --dry-run 預覽）"
 msgstr ""
 
-#: src/ring/commands/doctor.py:111
+#: src/ring/commands/doctor.py:114
 msgid "沒有 RiNG stale 狀態檔"
 msgstr ""
 
-#: src/ring/commands/doctor.py:116
+#: src/ring/commands/doctor.py:119
 msgid "設定檔"
 msgstr ""
 
-#: src/ring/commands/doctor.py:120
+#: src/ring/commands/doctor.py:123
 msgid "完整生效值請看 `ring config`。"
 msgstr ""
 
@@ -618,15 +622,15 @@ msgstr ""
 msgid "⚠️ 其中 {n} 段還在 🔴 等你（計到現在為止）。"
 msgstr ""
 
-#: src/ring/focus/__init__.py:56
+#: src/ring/focus/__init__.py:58
 msgid "已離場的 session 無法跳轉"
 msgstr ""
 
-#: src/ring/focus/__init__.py:69
+#: src/ring/focus/__init__.py:81
 msgid "找不到這個終端分頁（可能已關閉；刷新後若仍存在，請裝 hook 取得更精準狀態）"
 msgstr ""
 
-#: src/ring/focus/__init__.py:70
+#: src/ring/focus/__init__.py:82
 msgid "沒有 focuser 接得住（裝 hook，或一個專案只開一個 session 才測得到 tty）"
 msgstr ""