ring-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{ring_cli-0.2.0 → ring_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -27,6 +27,10 @@ Description-Content-Type: text/markdown
 
 [台灣漢語](https://github.com/Lee-W/ring/blob/main/README.md) · **English**
 
+[![PyPI](https://img.shields.io/pypi/v/ring-cli?label=PyPI)](https://pypi.org/project/ring-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/ring-cli)](https://pypi.org/project/ring-cli/)
+[![License](https://img.shields.io/pypi/l/ring-cli)](LICENSE)
+
 > **R**ealtime **I**nstance **N**otification **G**rid
 > — a local dashboard for active agent-CLI sessions. Claude Code and Codex are built in; other tools can plug in.
 
@@ -93,6 +97,7 @@ Zero-config mode can discover local Claude Code / Codex sessions without setup.
 ring install-hooks            # merges into Claude Code / Codex hook settings
 ring install-hooks --dry-run  # preview without writing
 ring doctor                   # inspect hooks, notification backends, focusers, and config
+ring gc --dry-run             # preview RiNG-owned stale state cleanup
 ```
 
 Hooks only apply to new sessions, so restart Claude Code / Codex sessions after installing.
@@ -112,6 +117,8 @@ Hooks only apply to new sessions, so restart Claude Code / Codex sessions after
 | `ring config` | Show config path and effective settings |
 | `ring config set KEY VALUE` | Write one config value |
 | `ring doctor` | Read-only environment diagnosis |
+| `ring gc --dry-run` | Preview RiNG-owned stale state cleanup |
+| `ring gc` | Clean RiNG-owned stale state files |
 
 ## Watch Mode
 
@@ -145,6 +152,22 @@ Without it, RiNG falls back to macOS text notifications without click-to-focus.
 Notification sound, repeat timing, and backend selection are configurable; notification backends
 are also pluggable via the `Notifier` extension point.
 
+### Cleaning RiNG State Files (`ring gc`)
+
+When RiNG receives `SessionEnd`, it removes its own hook registry entry. If an agent crashes or the
+final hook does not run, ended `~/.config/ring/sessions/*.json` files can remain. They are hidden from
+the board by default, and you can remove them with `ring gc`.
+
+```sh
+ring gc --dry-run        # preview what would be deleted
+ring gc                  # delete ended registry files older than 7 days, plus expired IPC files
+ring gc --older-than 1d  # use a 1-day threshold
+ring gc --all-ended      # delete every registry file currently classified as ended
+```
+
+`ring gc` only cleans state files RiNG owns under `~/.config/ring/`. It does not touch Claude Code /
+Codex transcripts or state. `ring doctor` remains read-only and never deletes files.
+
 ## Session Sources
 
 RiNG collects sessions from registered sources. Built-ins:

{ring_cli-0.2.0 → ring_cli-0.3.0}/README.en.md

@@ -2,6 +2,10 @@
 
 [台灣漢語](https://github.com/Lee-W/ring/blob/main/README.md) · **English**
 
+[![PyPI](https://img.shields.io/pypi/v/ring-cli?label=PyPI)](https://pypi.org/project/ring-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/ring-cli)](https://pypi.org/project/ring-cli/)
+[![License](https://img.shields.io/pypi/l/ring-cli)](LICENSE)
+
 > **R**ealtime **I**nstance **N**otification **G**rid
 > — a local dashboard for active agent-CLI sessions. Claude Code and Codex are built in; other tools can plug in.
 
@@ -68,6 +72,7 @@ Zero-config mode can discover local Claude Code / Codex sessions without setup.
 ring install-hooks            # merges into Claude Code / Codex hook settings
 ring install-hooks --dry-run  # preview without writing
 ring doctor                   # inspect hooks, notification backends, focusers, and config
+ring gc --dry-run             # preview RiNG-owned stale state cleanup
 ```
 
 Hooks only apply to new sessions, so restart Claude Code / Codex sessions after installing.
@@ -87,6 +92,8 @@ Hooks only apply to new sessions, so restart Claude Code / Codex sessions after
 | `ring config` | Show config path and effective settings |
 | `ring config set KEY VALUE` | Write one config value |
 | `ring doctor` | Read-only environment diagnosis |
+| `ring gc --dry-run` | Preview RiNG-owned stale state cleanup |
+| `ring gc` | Clean RiNG-owned stale state files |
 
 ## Watch Mode
 
@@ -120,6 +127,22 @@ Without it, RiNG falls back to macOS text notifications without click-to-focus.
 Notification sound, repeat timing, and backend selection are configurable; notification backends
 are also pluggable via the `Notifier` extension point.
 
+### Cleaning RiNG State Files (`ring gc`)
+
+When RiNG receives `SessionEnd`, it removes its own hook registry entry. If an agent crashes or the
+final hook does not run, ended `~/.config/ring/sessions/*.json` files can remain. They are hidden from
+the board by default, and you can remove them with `ring gc`.
+
+```sh
+ring gc --dry-run        # preview what would be deleted
+ring gc                  # delete ended registry files older than 7 days, plus expired IPC files
+ring gc --older-than 1d  # use a 1-day threshold
+ring gc --all-ended      # delete every registry file currently classified as ended
+```
+
+`ring gc` only cleans state files RiNG owns under `~/.config/ring/`. It does not touch Claude Code /
+Codex transcripts or state. `ring doctor` remains read-only and never deletes files.
+
 ## Session Sources
 
 RiNG collects sessions from registered sources. Built-ins:

{ring_cli-0.2.0 → ring_cli-0.3.0}/pyproject.toml

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

{ring_cli-0.2.0 → ring_cli-0.3.0}/src/ring/cli.py

@@ -10,13 +10,18 @@
 from __future__ import annotations
 
 import argparse
-import shutil
 import sys
 import time
+from dataclasses import fields
 from importlib.util import find_spec
 from typing import Any
 
 from ring import __version__
+from ring.commands._args import strip_lang as _strip_lang
+from ring.commands.doctor import run_doctor
+from ring.commands.focus import run_focus
+from ring.commands.gc import run_gc
+from ring.commands.hook import run_hook_command, run_install_hooks, run_remove_hooks
 from ring.config import CONFIG_PATH as CONFIG_PATH
 from ring.config import Config as Config
 from ring.config import ConfigError as ConfigError
@@ -26,7 +31,7 @@ from ring.i18n import gettext as _
 from ring.i18n import ngettext, set_lang
 from ring.labels import load_labels
 from ring.registry import Session, Status, running_agent_pids
-from ring.sources import discover_sessions, sources
+from ring.sources import discover_sessions
 
 try:
     from rich.box import SIMPLE_HEAD
@@ -74,14 +79,14 @@ def _middle_truncate(text: str, max_len: int) -> str:
        tmux 座標（如 ``main:1.0``）很短，自然走這條，不被動到。
 
     2. 否則以 ``/`` 為界，保留最後一層目錄完整：
-       ``tail = "/" + text.rsplit("/", 1)[-1]``，
+       ``tail = f"/{text.rsplit('/', 1)[-1]}"``，
        ``head_budget = max_len - 1 - len(tail)``（1 = ``…`` 的長度）。
-       若 ``head_budget >= 1``：回傳 ``text[:head_budget] + "…" + tail``。
+       若 ``head_budget >= 1``：回傳 ``f"{text[:head_budget]}…{tail}"``。
 
     3. ``head_budget < 1``（最後一層目錄名本身就超長，或 text 無 ``/``）：
        退化為純字元中段省略——
        ``keep = max_len - 1``；``front = (keep + 1) // 2``；``back = keep // 2``；
-       回傳 ``text[:front] + "…" + text[-back:]``（總長 == max_len）。
+       回傳 ``f"{text[:front]}…{text[-back:]}"``（總長 == max_len）。
 
     4. ``max_len <= 1`` 邊界：直接回傳 ``text[:max_len]``，避免負數切片。
 
@@ -92,17 +97,17 @@ def _middle_truncate(text: str, max_len: int) -> str:
     if len(text) <= max_len:
         return text
     # 以 / 為界，保留最後一層
-    tail = "/" + text.rsplit("/", 1)[-1]
+    tail = f"/{text.rsplit('/', 1)[-1]}"
     head_budget = max_len - 1 - len(tail)  # 1 for "…"
     if head_budget >= 1:
-        return text[:head_budget] + "…" + tail
+        return f"{text[:head_budget]}…{tail}"
     # 病態長尾段 fallback：純字元中段省略
     keep = max_len - 1
     front = (keep + 1) // 2
     back = keep // 2
     if back == 0:
         return text[:max_len]
-    return text[:front] + "…" + text[-back:]
+    return f"{text[:front]}…{text[-back:]}"
 
 
 def board(show_all: bool) -> list[Session]:
@@ -158,7 +163,7 @@ def _rich_renderable(sessions: list[Session], show_legend: bool, show_tool: bool
     if show_legend:
         blocks.append(_rich_legend())
     if not sessions:
-        blocks.append(Text("  " + _("（場館目前沒人上台）"), style=f"{_MUTED} italic"))
+        blocks.append(Text(f"  {_('（場館目前沒人上台）')}", style=f"{_MUTED} italic"))
         return Group(*blocks)
 
     table = Table(box=SIMPLE_HEAD, header_style="bold", pad_edge=False, expand=False)
@@ -196,7 +201,7 @@ def _render_plain(sessions: list[Session], show_legend: bool, show_tool: bool =
         items = "   ".join(f"{st.marker} {status_label(st)}" for st in Status)
         lines += ["", f"  {_('圖例')}   {items}"]
     if not sessions:
-        lines += ["", "  " + _("（場館目前沒人上台）")]
+        lines += ["", f"  {_('（場館目前沒人上台）')}"]
         return "\n".join(lines)
 
     labels = load_labels()
@@ -219,16 +224,12 @@ def _render_plain(sessions: list[Session], show_legend: bool, show_tool: bool =
     w_ago = max(len(c_idle), 3, *(len(r[4]) for r in rows))
     w_loc = max(len(c_loc), *(len(r[5]) for r in rows))
     tool_h = f"{c_tool:<{w_tool}}  " if show_tool else ""
-    header = (
-        f"     {tool_h}{c_proj:<{w_proj}}  {c_prog:>{w_prog}}  "
-        f"{c_idle:>{w_ago}}    {c_loc:<{w_loc}}  {c_act}"
-    )
+    header = f"     {tool_h}{c_proj:<{w_proj}}  {c_prog:>{w_prog}}  {c_idle:>{w_ago}}    {c_loc:<{w_loc}}  {c_act}"
     lines += ["", header]
     for marker, tool, project, prog, ago, loc, action in rows:
         tool_c = f"{tool:<{w_tool}}  " if show_tool else ""
         lines.append(
-            f"  {marker} {tool_c}{project:<{w_proj}}  {prog:>{w_prog}}  "
-            f"{ago:>{w_ago}}  📍{loc:<{w_loc}}  {action}"
+            f"  {marker} {tool_c}{project:<{w_proj}}  {prog:>{w_prog}}  {ago:>{w_ago}}  📍{loc:<{w_loc}}  {action}"
         )
     return "\n".join(lines)
 
@@ -247,7 +248,7 @@ def _format_config_value(value: object) -> str:
     if value is None:
         return "—"
     if isinstance(value, tuple):
-        return "[" + ", ".join(str(v) for v in value) + "]" if value else _("（內建預設）")
+        return f"[{', '.join(str(v) for v in value)}]" if value else _("（內建預設）")
     if isinstance(value, dict):
         return ", ".join(f"{k}={v}" for k, v in value.items())
     return str(value)
@@ -259,8 +260,6 @@ def print_config() -> None:
     欄位直接從 ``Config`` dataclass 列舉，所以新增設定不必再動這裡。值跟內建預設
     不同的會標一個箭頭，讓你一眼看出「我改過哪些」。
     """
-    from dataclasses import fields
-
     cfg = get_config()
     defaults = Config()
     exists = CONFIG_PATH.exists()
@@ -278,13 +277,11 @@ def print_config() -> None:
         print(f"  {f.name:<{width}}  {_format_config_value(value)}{mark}")
     print()
     hint = _("用 `ring config set KEY VALUE` 改，或直接編輯上面那個檔；完整選項見 src/ring/config.py 的 docstring。")
-    print("  " + hint)
+    print(f"  {hint}")
 
 
 def _config_get_value(key: str) -> object:
     """讀單一設定的目前生效值（支援 colors.<name> 點記法）。未知鍵丟 ConfigError。"""
-    from dataclasses import fields
-
     cfg = get_config()
     if "." in key:
         table, sub = key.split(".", 1)
@@ -296,23 +293,6 @@ def _config_get_value(key: str) -> object:
     raise ConfigError(_("未知的鍵：{key}", key=key))
 
 
-def _strip_lang(args: list[str]) -> list[str]:
-    """濾掉全域 ``--lang`` 旗標（已在 main 先 peek 過），只留 config 自己的位置參數。"""
-    out: list[str] = []
-    skip = False
-    for i, a in enumerate(args):
-        if skip:
-            skip = False
-            continue
-        if a == "--lang":
-            skip = i + 1 < len(args)  # 連同它的值一起跳過
-            continue
-        if a.startswith("--lang="):
-            continue
-        out.append(a)
-    return out
-
-
 def run_config(args: list[str]) -> int:
     """``ring config`` 進入點：無參數→列表；``get KEY``→讀；``set KEY VALUE``→寫。"""
     args = _strip_lang(args)
@@ -343,136 +323,13 @@ def run_config(args: list[str]) -> int:
             print(f"⚠️ {e}", file=sys.stderr)
             return 1
         print(_("✅ 已設定 {key} = {value}（{path}）", key=key, value=_format_config_value(coerced), path=CONFIG_PATH))
-        print("   " + _("註：set 會重寫整個設定檔，原有註解不會保留。"))
+        print(f"   {_('註：set 會重寫整個設定檔，原有註解不會保留。')}")
         return 0
 
     print(_("未知的 config 動作：{action}（用 get / set，或不帶參數看目前設定）", action=action), file=sys.stderr)
     return 2
 
 
-def run_doctor(args: list[str]) -> int:
-    """``ring doctor`` 進入點：唯讀環境診斷，印出五節報告，固定回 0。args 非空回 2。"""
-    args = _strip_lang(args)
-    if args:
-        print(_("用法：ring doctor"), file=sys.stderr)
-        return 2
-
-    from ring.focus import focusers
-    from ring.hook import hook_status
-    from ring.notify import _select_notifier, notifiers
-    from ring.osascript import osascript
-
-    cfg = get_config()
-
-    print(_("RiNG 環境診斷"))
-    print(f"  {_('狀態')}：{_('唯讀檢查，不會改動任何設定')}")
-    print()
-
-    # ── (a) Session 來源 ────────────────────────────────────────────────────
-    print(_("Session 來源"))
-    src_list = sources()
-    if src_list:
-        width_src = max(len(s.name) for s in src_list)
-    else:
-        width_src = 10
-    for src in src_list:
-        try:
-            found = src.discover()
-            n = len(found)
-            status_str = _("活著")
-            count_str = _("偵測到 {n} 個 session", n=n)
-            print(f"  {src.name:<{width_src}}  {status_str}    {count_str}")
-        except Exception:
-            print(f"  {src.name:<{width_src}}  {_('偵測失敗')}")
-    print()
-
-    # ── (b) Hook 安裝 ────────────────────────────────────────────────────────
-    print(_("Hook 安裝"))
-    statuses = hook_status()
-    provider_labels = {"claude-code": "Claude Code", "codex": "Codex"}
-    if statuses:
-        width_hook = max(len(provider_labels.get(s.provider, s.provider)) for s in statuses)
-    else:
-        width_hook = 10
-    for hs in statuses:
-        label = provider_labels.get(hs.provider, hs.provider)
-        if not hs.applicable:
-            msg = _("未使用 Codex（zero-config）")
-        elif hs.installed:
-            msg = _("已安裝")
-        else:
-            msg = _("未安裝（執行 ring install-hooks）")
-        print(f"  {label:<{width_hook}}  {msg}")
-    print()
-
-    # ── (c) 通知後端 ─────────────────────────────────────────────────────────
-    print(_("通知後端"))
-    print(f"  {_('目前設定')}：{cfg.notify_backend}")
-    notifier_list = notifiers()
-    if notifier_list:
-        width_n = max(len(nt.name) for nt in notifier_list)
-    else:
-        width_n = 10
-    for nt in notifier_list:
-        avail_str = _("可用") if nt.available() else _("不可用")
-        print(f"  {nt.name:<{width_n}}  {avail_str}")
-    selected = _select_notifier(cfg.notify_backend)
-    if selected is not None:
-        print(f"  {_('auto 實際選中')}：{selected.name}")
-        if sys.platform == "darwin" and selected.name in {"terminal-notifier", "osascript"}:
-            print(
-                "  "
-                + _(
-                    "macOS 提醒：若只聽到聲音但沒有通知框，請到系統設定的通知項目啟用 Banner/Alert。"
-                )
-            )
-    else:
-        # 附原因
-        if cfg.notify_backend == "none":
-            reason = _("backend=none")
-        elif cfg.notify_backend == "agent-hooks" and shutil.which("agent-hooks") is not None:
-            reason = _("agent-hooks 已接手")
-        else:
-            reason = _("全部不可用")
-        print(f"  {_('auto 實際選中')}：{_('不發通知')}（{reason}）")
-    print()
-
-    # ── (d) 聚焦終端（focuser）───────────────────────────────────────────────
-    print(_("聚焦終端（focuser）"))
-    focuser_list = focusers()
-    if focuser_list:
-        width_f = max(len(f.name) for f in focuser_list)
-    else:
-        width_f = 10
-    for f in focuser_list:
-        name_lower = f.name.lower()
-        if name_lower == "tmux":
-            avail = shutil.which("tmux") is not None
-            avail_str = _("可用") if avail else _("不可用（tmux 不在 PATH）")
-        else:
-            # iTerm2 / Terminal：先確認 osascript 在，再問 app 是否跑著
-            if shutil.which("osascript") is None:
-                avail_str = _("不可用（osascript 不在 PATH）")
-            else:
-                app_name = f.name  # "iTerm2" or "Terminal"
-                try:
-                    rc, out, _err = osascript(f'application "{app_name}" is running')
-                    avail_str = _("可用") if (rc == 0 and out == "true") else _("不可用（app 沒在跑）")
-                except Exception:
-                    avail_str = _("不可用（app 沒在跑）")
-        print(f"  {f.name:<{width_f}}  {avail_str}")
-    print()
-
-    # ── (e) 設定檔 ───────────────────────────────────────────────────────────
-    print(_("設定檔"))
-    exists = CONFIG_PATH.exists()
-    print(f"  {_('路徑')}：{CONFIG_PATH}")
-    print(f"  {_('狀態')}：{_('已存在') if exists else _('不存在（全部用內建預設）')}")
-    print(f"  {_('完整生效值請看 `ring config`。')}")
-
-    return 0
-
-
 def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int:
     from ring.notify import notify_waiting
     from ring.watcher import WaitingAlertScheduler
@@ -494,7 +351,7 @@ def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int
                 except Exception:
                     pass
                 print(_render_plain(sessions, show_legend, show_tool_column(sessions)))
-                print("\n" + footer_text)
+                print(f"\n{footer_text}")
                 sys.stdout.flush()
                 frames += 1
                 if count and frames >= count:
@@ -517,7 +374,7 @@ def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int
                 except Exception:
                     pass
                 body = _rich_renderable(sessions, show_legend, show_tool_column(sessions))
-                live.update(Group(body, Text("\n" + footer_text, style=_MUTED)), refresh=True)
+                live.update(Group(body, Text(f"\n{footer_text}", style=_MUTED)), refresh=True)
                 frames += 1
                 if count and frames >= count:
                     return 0
@@ -548,7 +405,8 @@ commands:
   config get KEY               讀單一設定的目前值
   config set KEY VALUE         寫入單一設定（會重寫設定檔，不保留註解）
   focus SESSION_ID             聚焦指定 session；TUI 在跑時會回到 RiNG 並選中該列
-  doctor                       顯示環境診斷（唯讀）——hook 安裝狀態、通知後端、focuser 可用性
+  gc [--dry-run]               清理 RiNG 自己的 stale 狀態檔
+  doctor                       顯示環境診斷（唯讀）——hook、通知、focuser、維護提示
 """
     )
 
@@ -585,12 +443,23 @@ def _subcommand_help(name: str) -> str:
             """usage: ring focus SESSION_ID
 
 聚焦指定 session；若 RiNG TUI 正在執行，會回到 TUI 並選中該列。
+"""
+        ),
+        "gc": _(
+            """usage: ring gc [--dry-run] [--older-than DURATION] [--all-ended]
+
+清理 RiNG 自己的 stale 狀態檔；不碰 Claude Code / Codex 的 transcript 或 state。
+
+options:
+  --dry-run              只預覽，不刪檔
+  --older-than DURATION  清理超過指定時間的已離場 registry（例如 30m、2h、7d；預設 7d）
+  --all-ended            清理所有目前判定已離場的 registry
 """
         ),
         "doctor": _(
             """usage: ring doctor
 
-唯讀環境診斷：逐節報告 hook 安裝狀態、通知後端可用性、focuser 可用性與設定檔位置。
+唯讀環境診斷：逐節報告 hook 安裝狀態、通知後端可用性、focuser 可用性、維護提示與設定檔位置。
 不寫任何檔案、不安裝、不發通知；固定回傳 0。
 """
         ),
@@ -603,53 +472,28 @@ def main(argv: list[str] | None = None) -> int:
     cfg = get_config()
     set_lang(_peek_lang(raw) or cfg.lang)  # 在 import ring.tui 前設好，Footer 按鍵說明也跟著語言
 
-    if raw and raw[0] in {"hook", "install-hooks", "remove-hooks", "config", "focus", "doctor"} and any(
-        arg in {"-h", "--help"} for arg in raw[1:]
+    if (
+        raw
+        and raw[0] in {"hook", "install-hooks", "remove-hooks", "config", "focus", "gc", "doctor"}
+        and any(arg in {"-h", "--help"} for arg in raw[1:])
     ):
         print(_subcommand_help(raw[0]), end="")
         return 0
 
     if raw and raw[0] == "hook":
-        from ring.hook import run_hook
-
-        provider = "claude-code"
-        hook_args = raw[1:]
-        if hook_args:
-            if hook_args[0] == "--provider" and len(hook_args) >= 2:
-                provider = hook_args[1]
-            elif hook_args[0].startswith("--provider="):
-                provider = hook_args[0].split("=", 1)[1]
-            elif not hook_args[0].startswith("-"):
-                provider = hook_args[0]
-        return run_hook(provider=provider)
+        return run_hook_command(raw[1:])
     if raw and raw[0] == "install-hooks":
-        from ring.hook import install_hooks
-
-        return install_hooks(dry_run="--dry-run" in raw)
+        return run_install_hooks(raw[1:])
     if raw and raw[0] == "remove-hooks":
-        from ring.hook import uninstall_hooks
-
-        return uninstall_hooks(dry_run="--dry-run" in raw)
+        return run_remove_hooks(raw[1:])
     if raw and raw[0] == "config":
         return run_config(raw[1:])
+    if raw and raw[0] == "gc":
+        return run_gc(raw[1:])
     if raw and raw[0] == "doctor":
         return run_doctor(raw[1:])
     if raw and raw[0] == "focus" and len(raw) >= 2:
-        from ring.focus import jump as focus_jump
-        from ring.ipc import read_tui_presence, write_focus_request
-        from ring.sources import get_by_id
-
-        session = get_by_id(raw[1])
-        if session is None:
-            return 0
-        presence = read_tui_presence()
-        if presence is not None:
-            # TUI 在跑：寫 focus-request，讓 TUI 自己移游標並 activate 視窗。
-            write_focus_request(raw[1])
-        else:
-            # headless（沒有 TUI 在跑）：退化回現行行為——直接跳到 claude 所在終端。
-            focus_jump(session)
-        return 0
+        return run_focus(raw[1:])
 
     parser = argparse.ArgumentParser(
         prog="ring",

ring_cli-0.3.0/src/ring/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI 子命令 handlers。"""

ring_cli-0.3.0/src/ring/commands/_args.py

@@ -0,0 +1,20 @@
+"""CLI argument helpers shared by subcommands."""
+
+from __future__ import annotations
+
+
+def strip_lang(args: list[str]) -> list[str]:
+    """濾掉全域 ``--lang`` 旗標（已在 main 先 peek 過），只留子命令自己的參數。"""
+    out: list[str] = []
+    skip = False
+    for i, a in enumerate(args):
+        if skip:
+            skip = False
+            continue
+        if a == "--lang":
+            skip = i + 1 < len(args)
+            continue
+        if a.startswith("--lang="):
+            continue
+        out.append(a)
+    return out

ring_cli-0.3.0/src/ring/commands/doctor.py

@@ -0,0 +1,122 @@
+"""``ring doctor`` command handler."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+
+from ring.commands._args import strip_lang
+from ring.config import CONFIG_PATH, get_config
+from ring.gc import DEFAULT_OLDER_THAN_SECONDS
+from ring.gc import collect_candidates as gc_collect_candidates
+from ring.i18n import gettext as _
+from ring.sources import sources
+
+
+def run_doctor(args: list[str]) -> int:
+    """唯讀環境診斷，印出各節報告，固定回 0。args 非空回 2。"""
+    args = strip_lang(args)
+    if args:
+        print(_("用法：ring doctor"), file=sys.stderr)
+        return 2
+
+    from ring.focus import focusers
+    from ring.hook import hook_status
+    from ring.notify import _select_notifier, notifiers
+    from ring.osascript import osascript
+
+    cfg = get_config()
+
+    print(_("RiNG 環境診斷"))
+    print(f"  {_('狀態')}：{_('唯讀檢查，不會改動任何設定')}")
+    print()
+
+    print(_("Session 來源"))
+    src_list = sources()
+    width_src = max(len(s.name) for s in src_list) if src_list else 10
+    for src in src_list:
+        try:
+            found = src.discover()
+            n = len(found)
+            status_str = _("活著")
+            count_str = _("偵測到 {n} 個 session", n=n)
+            print(f"  {src.name:<{width_src}}  {status_str}    {count_str}")
+        except Exception:
+            print(f"  {src.name:<{width_src}}  {_('偵測失敗')}")
+    print()
+
+    print(_("Hook 安裝"))
+    statuses = hook_status()
+    provider_labels = {"claude-code": "Claude Code", "codex": "Codex"}
+    width_hook = max(len(provider_labels.get(s.provider, s.provider)) for s in statuses) if statuses else 10
+    for hs in statuses:
+        label = provider_labels.get(hs.provider, hs.provider)
+        if not hs.applicable:
+            msg = _("未使用 Codex（zero-config）")
+        elif hs.installed:
+            msg = _("已安裝")
+        else:
+            msg = _("未安裝（執行 ring install-hooks）")
+        print(f"  {label:<{width_hook}}  {msg}")
+    print()
+
+    print(_("通知後端"))
+    print(f"  {_('目前設定')}：{cfg.notify_backend}")
+    notifier_list = notifiers()
+    width_n = max(len(nt.name) for nt in notifier_list) if notifier_list else 10
+    for nt in notifier_list:
+        avail_str = _("可用") if nt.available() else _("不可用")
+        print(f"  {nt.name:<{width_n}}  {avail_str}")
+    selected = _select_notifier(cfg.notify_backend)
+    if selected is not None:
+        print(f"  {_('auto 實際選中')}：{selected.name}")
+        if sys.platform == "darwin" and selected.name in {"terminal-notifier", "osascript"}:
+            print(f"  {_('macOS 提醒：若只聽到聲音但沒有通知框，請到系統設定的通知項目啟用 Banner/Alert。')}")
+    else:
+        if cfg.notify_backend == "none":
+            reason = _("backend=none")
+        elif cfg.notify_backend == "agent-hooks" and shutil.which("agent-hooks") is not None:
+            reason = _("agent-hooks 已接手")
+        else:
+            reason = _("全部不可用")
+        print(f"  {_('auto 實際選中')}：{_('不發通知')}（{reason}）")
+    print()
+
+    print(_("聚焦終端（focuser）"))
+    focuser_list = focusers()
+    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":
+            avail = shutil.which("tmux") is not None
+            avail_str = _("可用") if avail else _("不可用（tmux 不在 PATH）")
+        elif shutil.which("osascript") is None:
+            avail_str = _("不可用（osascript 不在 PATH）")
+        else:
+            app_name = f.name
+            try:
+                rc, out, _err = osascript(f'application "{app_name}" is running')
+                avail_str = _("可用") if (rc == 0 and out == "true") else _("不可用（app 沒在跑）")
+            except Exception:
+                avail_str = _("不可用（app 沒在跑）")
+        print(f"  {f.name:<{width_f}}  {avail_str}")
+    print()
+
+    print(_("維護"))
+    try:
+        candidates = gc_collect_candidates(older_than=DEFAULT_OLDER_THAN_SECONDS)
+        if candidates:
+            print(f"  {_('可清理')}：{_('{n} 個 RiNG stale 狀態檔（執行 ring gc --dry-run 預覽）', n=len(candidates))}")
+        else:
+            print(f"  {_('可清理')}：{_('沒有 RiNG stale 狀態檔')}")
+    except Exception:
+        print(f"  {_('可清理')}：{_('偵測失敗')}")
+    print()
+
+    print(_("設定檔"))
+    exists = CONFIG_PATH.exists()
+    print(f"  {_('路徑')}：{CONFIG_PATH}")
+    print(f"  {_('狀態')}：{_('已存在') if exists else _('不存在（全部用內建預設）')}")
+    print(f"  {_('完整生效值請看 `ring config`。')}")
+
+    return 0

ring_cli-0.3.0/src/ring/commands/focus.py

@@ -0,0 +1,23 @@
+"""``ring focus`` command handler."""
+
+from __future__ import annotations
+
+
+def run_focus(args: list[str]) -> int:
+    if len(args) < 1:
+        return 0
+
+    from ring.focus import jump as focus_jump
+    from ring.ipc import read_tui_presence, write_focus_request
+    from ring.sources import get_by_id
+
+    session_id = args[0]
+    session = get_by_id(session_id)
+    if session is None:
+        return 0
+    presence = read_tui_presence()
+    if presence is not None:
+        write_focus_request(session_id)
+    else:
+        focus_jump(session)
+    return 0

ring_cli-0.3.0/src/ring/commands/gc.py

@@ -0,0 +1,46 @@
+"""``ring gc`` command handler."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ring.commands._args import strip_lang
+from ring.gc import DEFAULT_OLDER_THAN_SECONDS, parse_duration
+from ring.gc import run_gc as gc_run
+from ring.i18n import gettext as _
+
+
+def run_gc(args: list[str]) -> int:
+    """清理 RiNG 自己的 stale 狀態檔。"""
+    args = strip_lang(args)
+
+    parser = argparse.ArgumentParser(prog="ring gc", description=_("清理 RiNG 自己的 stale 狀態檔。"))
+    parser.add_argument("--dry-run", action="store_true", help=_("只預覽，不刪檔"))
+    parser.add_argument(
+        "--older-than",
+        default="7d",
+        metavar="DURATION",
+        help=_("清理超過指定時間的已離場 registry（例如 30m、2h、7d；預設 7d）"),
+    )
+    parser.add_argument("--all-ended", action="store_true", help=_("清理所有目前判定已離場的 registry"))
+    try:
+        ns = parser.parse_args(args)
+        older_than = parse_duration(ns.older_than) if ns.older_than else DEFAULT_OLDER_THAN_SECONDS
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else 2
+    except ValueError:
+        print(_("無效的 --older-than：{value}", value=ns.older_than), file=sys.stderr)
+        return 2
+
+    result = gc_run(older_than=older_than, all_ended=ns.all_ended, dry_run=ns.dry_run)
+    action = _("將刪除") if result.dry_run else _("已刪除")
+    count = len(result.candidates) if result.dry_run else len(result.deleted)
+    print(_("RiNG GC：{action} {count} 個檔案", action=action, count=count))
+    shown = result.candidates if result.dry_run else result.deleted
+    for candidate in shown:
+        prefix = "  - " if result.dry_run else "  ✓ "
+        print(f"{prefix}{candidate.path} ({candidate.reason})")
+    for candidate, error in result.errors:
+        print(f"  ! {candidate.path} ({error})", file=sys.stderr)
+    return 1 if result.errors else 0

ring_cli-0.3.0/src/ring/commands/hook.py

@@ -0,0 +1,29 @@
+"""Hook-related CLI command handlers."""
+
+from __future__ import annotations
+
+
+def run_hook_command(args: list[str]) -> int:
+    from ring.hook import run_hook
+
+    provider = "claude-code"
+    if args:
+        if args[0] == "--provider" and len(args) >= 2:
+            provider = args[1]
+        elif args[0].startswith("--provider="):
+            provider = args[0].split("=", 1)[1]
+        elif not args[0].startswith("-"):
+            provider = args[0]
+    return run_hook(provider=provider)
+
+
+def run_install_hooks(args: list[str]) -> int:
+    from ring.hook import install_hooks
+
+    return install_hooks(dry_run="--dry-run" in args)
+
+
+def run_remove_hooks(args: list[str]) -> int:
+    from ring.hook import uninstall_hooks
+
+    return uninstall_hooks(dry_run="--dry-run" in args)

ring_cli-0.3.0/src/ring/gc.py

@@ -0,0 +1,152 @@
+"""RiNG 自有狀態檔清理。
+
+只清 RiNG 寫在 ``~/.config/ring/`` 底下的檔案；不碰 Claude Code / Codex 的
+transcript、SQLite state 或任何 provider 原始資料。
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from ring.ipc import _FOCUS_REQUEST_PATH, _PRESENCE_PATH, _PRESENCE_TTL, _REQUEST_TTL
+from ring.registry import (
+    _SESSION_START_SOURCES,
+    RING_REGISTRY,
+    Status,
+    _hook_sessions,
+    collect_provider_procs,
+)
+
+DEFAULT_OLDER_THAN_SECONDS = 7 * 24 * 60 * 60
+
+
+@dataclass(frozen=True)
+class GcCandidate:
+    path: Path
+    reason: str
+
+
+@dataclass(frozen=True)
+class GcResult:
+    candidates: list[GcCandidate]
+    deleted: list[GcCandidate]
+    errors: list[tuple[GcCandidate, str]]
+    dry_run: bool
+
+
+def parse_duration(raw: str) -> float:
+    """解析簡單 duration：``30s``、``10m``、``2h``、``7d``，無單位視為秒。"""
+    text = raw.strip().lower()
+    if not text:
+        raise ValueError("empty duration")
+    unit = text[-1]
+    if unit in {"s", "m", "h", "d"}:
+        number = text[:-1]
+        factor = {"s": 1, "m": 60, "h": 3600, "d": 86400}[unit]
+    else:
+        number = text
+        factor = 1
+    seconds = float(number) * factor
+    if seconds < 0:
+        raise ValueError("negative duration")
+    return seconds
+
+
+def collect_candidates(*, older_than: float, all_ended: bool = False, now: float | None = None) -> list[GcCandidate]:
+    """收集可清理的 RiNG 自有狀態檔。"""
+    current = time.time() if now is None else now
+    candidates: dict[Path, GcCandidate] = {}
+
+    for candidate in _registry_candidates(older_than=older_than, all_ended=all_ended, now=current):
+        candidates[candidate.path] = candidate
+    for candidate in _ipc_candidates(now=current):
+        candidates[candidate.path] = candidate
+
+    return sorted(candidates.values(), key=lambda c: str(c.path))
+
+
+def run_gc(
+    *, older_than: float = DEFAULT_OLDER_THAN_SECONDS, all_ended: bool = False, dry_run: bool = False
+) -> GcResult:
+    candidates = collect_candidates(older_than=older_than, all_ended=all_ended)
+    deleted: list[GcCandidate] = []
+    errors: list[tuple[GcCandidate, str]] = []
+    if dry_run:
+        return GcResult(candidates=candidates, deleted=deleted, errors=errors, dry_run=True)
+
+    for candidate in candidates:
+        try:
+            candidate.path.unlink(missing_ok=True)
+            deleted.append(candidate)
+        except OSError as e:
+            errors.append((candidate, str(e)))
+    return GcResult(candidates=candidates, deleted=deleted, errors=errors, dry_run=False)
+
+
+def _registry_candidates(*, older_than: float, all_ended: bool, now: float) -> list[GcCandidate]:
+    if not RING_REGISTRY.is_dir():
+        return []
+
+    candidates: list[GcCandidate] = []
+    sessions = _hook_sessions(
+        procs_by_provider=collect_provider_procs(),
+        purge_session_start_phantoms=False,
+    )
+    ended = {s.session_id: s for s in sessions if s.status is Status.ENDED}
+
+    for path in RING_REGISTRY.glob("*.json"):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            candidates.append(GcCandidate(path, "registry JSON 無法讀取"))
+            continue
+
+        provider = str(data.get("provider", "claude-code") or "claude-code")
+        if provider in _SESSION_START_SOURCES:
+            candidates.append(GcCandidate(path, "舊版 SessionStart 幽靈檔"))
+            continue
+
+        sid = str(data.get("session_id", ""))
+        session = ended.get(sid)
+        if session is None:
+            continue
+
+        last_active = _last_active(data)
+        if all_ended or now - last_active >= older_than:
+            candidates.append(GcCandidate(path, "已離場 registry"))
+
+    return candidates
+
+
+def _ipc_candidates(*, now: float) -> list[GcCandidate]:
+    candidates: list[GcCandidate] = []
+    candidates.extend(_stale_json_file(_FOCUS_REQUEST_PATH, ttl=_REQUEST_TTL, now=now, label="focus-request"))
+    candidates.extend(_stale_json_file(_PRESENCE_PATH, ttl=_PRESENCE_TTL, now=now, label="tui-presence"))
+    return candidates
+
+
+def _stale_json_file(path: Path, *, ttl: float, now: float, label: str) -> list[GcCandidate]:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    try:
+        data = json.loads(raw)
+        ts = float(data["ts"])
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+        return [GcCandidate(path, f"{label} JSON 無法讀取")]
+    if now - ts > ttl:
+        return [GcCandidate(path, f"{label} 已過期")]
+    return []
+
+
+def _last_active(data: object) -> float:
+    if not isinstance(data, dict):
+        return 0.0
+    try:
+        return float(data.get("last_active", 0.0))
+    except (TypeError, ValueError):
+        return 0.0

{ring_cli-0.2.0 → ring_cli-0.3.0}/src/ring/registry.py

@@ -771,6 +771,7 @@ def _hook_sessions(
     procs: list[tuple[str, str]] | None = None,
     *,
     procs_by_provider: dict[str, list[tuple[str, str]]] | None = None,
+    purge_session_start_phantoms: bool = True,
 ) -> list[Session]:
     if not RING_REGISTRY.is_dir():
         return []
@@ -786,7 +787,8 @@ def _hook_sessions(
             if provider in _SESSION_START_SOURCES:
                 # 舊版 bug 把 SessionStart 的 source（startup/resume/clear/compact）誤當
                 # provider，留下無 tty、跳不過去、又永不離場的幽靈列。清掉這種腐壞檔，自我修復。
-                f.unlink(missing_ok=True)
+                if purge_session_start_phantoms:
+                    f.unlink(missing_ok=True)
                 continue
             out.append(
                 Session(