ring-cli 0.2.0__py3-none-any.whl

ring/config.py

@@ -0,0 +1,276 @@
+"""RiNG 設定檔：``~/.config/ring/config.toml``。
+
+缺檔、缺鍵、型別錯——全部安靜退回預設，所以零設定也能跑。範例：
+
+    lang = "en"
+    interval = 1.5
+    show_all = false
+    legend = true
+    active_window_seconds = 21600     # 只看最近這段時間動過的 session（預設 6h）
+    working_threshold_seconds = 90    # 多久沒動就從 🟢 工作中 變 🟡 閒置
+    waiting_window_seconds = 1800     # 跑完停著升等你的時間窗上限（預設 30 分）
+    notify_sound = true               # 系統通知帶聲音
+    notify_sound_name = "Glass"       # macOS / terminal-notifier sound name
+    notify_ignore_dnd = false         # terminal-notifier 是否加 -ignoreDnD（穿透勿擾 / Focus）
+    notify_backend = "auto"           # auto / terminal-notifier / osascript / notify-send / agent-hooks / none
+                                      #   terminal-notifier 被 macOS 擋掉時設 "osascript"
+                                      #   （看得到通知，但點擊不跳轉）；
+                                      #   "agent-hooks" = 決策+提醒交給 agent-hooks（ring hook 同步出 modal，
+                                      #     沒裝時自動退回 auto 通知）；
+                                      #   "none" = 完全不發通知（RiNG 當純看板）
+    notify_repeat_seconds = [30, 120, 300]  # 持續等你時，多久後重複提醒
+    notify_repeat_max = 3             # 重複提醒上限；0 = 不限
+    focusers = ["tmux", "iTerm2", "Terminal"]   # 跳轉嘗試順序；省略＝內建預設
+"""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".config" / "ring" / "config.toml"
+
+# Rich 樣式字串。深淺底都看得到（避開 dim / ANSI blue）。config 的 [colors] 可逐項覆寫。
+_DEFAULT_COLORS = {
+    "waiting": "bold red",
+    "working": "green",
+    "idle": "yellow",
+    "ended": "grey50",
+    "project": "cyan",
+    "location": "bright_blue",
+    "muted": "grey50",
+}
+
+
+@dataclass(frozen=True)
+class Config:
+    lang: str | None = None
+    interval: float = 2.0
+    show_all: bool = False
+    legend: bool = True
+    active_window_seconds: int = 6 * 60 * 60
+    working_threshold_seconds: int = 90
+    waiting_window_seconds: int = 1800  # 跑完停著升等你的時間窗上限（預設 30 分）
+    notify_sound: bool = True
+    notify_sound_name: str = "Glass"
+    notify_ignore_dnd: bool = False
+    # 通知後端（完整說明見模組 docstring）：
+    #   auto = 第一個可用後端（優先支援點擊跳轉的 terminal-notifier）；
+    #   terminal-notifier / osascript / notify-send = 強制指定該後端；
+    #   agent-hooks = 決策+提醒交給 agent-hooks（沒裝時自動退回 auto）；
+    #   none = 完全不發通知（RiNG 當純看板）。
+    notify_backend: str = "auto"
+    notify_repeat_seconds: tuple[int, ...] = (30, 120, 300)
+    notify_repeat_max: int = 3  # 0 = 不限
+    focusers: tuple[str, ...] = ()  # 空＝用內建預設順序
+    colors: dict[str, str] = field(default_factory=lambda: dict(_DEFAULT_COLORS))
+
+
+def _as_int(v: object, default: int) -> int:
+    return v if isinstance(v, int) and not isinstance(v, bool) else default
+
+
+def _as_float(v: object, default: float) -> float:
+    if isinstance(v, (int, float)) and not isinstance(v, bool):
+        return float(v)
+    return default
+
+
+def _as_bool(v: object, default: bool) -> bool:
+    return v if isinstance(v, bool) else default
+
+
+def _as_str_tuple(v: object) -> tuple[str, ...]:
+    if isinstance(v, list):
+        return tuple(x for x in v if isinstance(x, str))
+    return ()
+
+
+def _as_positive_int_tuple(v: object, default: tuple[int, ...]) -> tuple[int, ...]:
+    if isinstance(v, list):
+        parsed = tuple(x for x in v if isinstance(x, int) and not isinstance(x, bool) and x > 0)
+        return parsed or default
+    return default
+
+
+def _parse_colors(v: object) -> dict[str, str]:
+    colors = dict(_DEFAULT_COLORS)
+    if isinstance(v, dict):
+        colors.update({k: val for k, val in v.items() if isinstance(k, str) and isinstance(val, str)})
+    return colors
+
+
+def load(path: Path | None = None) -> Config:
+    p = path or CONFIG_PATH
+    try:
+        raw = tomllib.loads(p.read_text())
+    except (OSError, tomllib.TOMLDecodeError):
+        return Config()
+    d = Config()
+    lang = raw.get("lang")
+    # 任意非空字串都接受（後端名稱由 notify 層的可插拔 registry 決定）；認不得的名稱
+    # 會在送通知時退回 auto 選法。非字串 / 空字串 → 預設 "auto"。
+    nb = raw.get("notify_backend")
+    notify_backend = nb if isinstance(nb, str) and nb else d.notify_backend
+    return Config(
+        lang=lang if isinstance(lang, str) else None,
+        interval=_as_float(raw.get("interval"), d.interval),
+        show_all=_as_bool(raw.get("show_all"), d.show_all),
+        legend=_as_bool(raw.get("legend"), d.legend),
+        active_window_seconds=_as_int(raw.get("active_window_seconds"), d.active_window_seconds),
+        working_threshold_seconds=_as_int(raw.get("working_threshold_seconds"), d.working_threshold_seconds),
+        waiting_window_seconds=_as_int(raw.get("waiting_window_seconds"), d.waiting_window_seconds),
+        notify_sound=_as_bool(raw.get("notify_sound"), d.notify_sound),
+        notify_sound_name=(
+            raw["notify_sound_name"] if isinstance(raw.get("notify_sound_name"), str) else d.notify_sound_name
+        ),
+        notify_ignore_dnd=_as_bool(raw.get("notify_ignore_dnd"), d.notify_ignore_dnd),
+        notify_repeat_seconds=_as_positive_int_tuple(raw.get("notify_repeat_seconds"), d.notify_repeat_seconds),
+        notify_repeat_max=max(0, _as_int(raw.get("notify_repeat_max"), d.notify_repeat_max)),
+        notify_backend=notify_backend,
+        focusers=_as_str_tuple(raw.get("focusers")),
+        colors=_parse_colors(raw.get("colors")),
+    )
+
+
+@lru_cache(maxsize=1)
+def get_config() -> Config:
+    """整個 process 共用的設定（讀一次）。要繞過快取自訂就直接呼叫 load(path)。"""
+    return load()
+
+
+# --------------------------------------------------------------------------- 寫入（ring config set）
+
+
+class ConfigError(ValueError):
+    """``ring config set/get`` 的使用者層級錯誤（未知鍵 / 值轉型失敗）。訊息直接給使用者看。"""
+
+
+def _coerce_bool(s: str) -> bool:
+    low = s.strip().lower()
+    if low in {"true", "1", "yes", "on"}:
+        return True
+    if low in {"false", "0", "no", "off"}:
+        return False
+    raise ConfigError(f"'{s}' 不是布林值（用 true / false）")
+
+
+def _coerce_int(s: str) -> int:
+    try:
+        return int(s.strip())
+    except ValueError:
+        raise ConfigError(f"'{s}' 不是整數") from None
+
+
+def _coerce_float(s: str) -> float:
+    try:
+        return float(s.strip())
+    except ValueError:
+        raise ConfigError(f"'{s}' 不是數字") from None
+
+
+def _coerce_int_list(s: str) -> list[int]:
+    return [_coerce_int(part) for part in s.split(",") if part.strip()]
+
+
+def _coerce_str_list(s: str) -> list[str]:
+    return [part.strip() for part in s.split(",") if part.strip()]
+
+
+# 可由 ``ring config set`` 寫入的純量 / 清單鍵 → 把 CLI 傳來的字串轉成對應型別。
+# colors 是巢狀 table，用 ``colors.<name>`` 點記法另外處理（見 set_value）。
+_SETTERS: dict[str, Callable[[str], object]] = {
+    "lang": str,
+    "interval": _coerce_float,
+    "show_all": _coerce_bool,
+    "legend": _coerce_bool,
+    "active_window_seconds": _coerce_int,
+    "working_threshold_seconds": _coerce_int,
+    "waiting_window_seconds": _coerce_int,
+    "notify_sound": _coerce_bool,
+    "notify_sound_name": str,
+    "notify_ignore_dnd": _coerce_bool,
+    "notify_backend": str,
+    "notify_repeat_seconds": _coerce_int_list,
+    "notify_repeat_max": _coerce_int,
+    "focusers": _coerce_str_list,
+}
+
+
+def settable_keys() -> list[str]:
+    """``ring config set`` 接受的鍵（colors 子鍵用 colors.<name>，不在此列）。"""
+    return list(_SETTERS)
+
+
+def _toml_repr(value: object) -> str:
+    """把一個 Python 值序列化成 TOML 字面值（只涵蓋本設定會用到的型別）。"""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return repr(value)
+    if isinstance(value, str):
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+        return f'"{escaped}"'
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(_toml_repr(v) for v in value) + "]"
+    raise ConfigError(f"無法序列化 {type(value).__name__} 值")
+
+
+def dump_toml(data: dict[str, object]) -> str:
+    """把設定 dict 寫成 TOML 文字。純量 / 清單在前，巢狀 table（如 [colors]）殿後。
+
+    刻意樸素：不保留註解（``ring config set`` 重寫整檔），但所有鍵值都會保留。
+    """
+    lines = [f"{k} = {_toml_repr(v)}" for k, v in data.items() if not isinstance(v, dict)]
+    for k, v in data.items():
+        if isinstance(v, dict):
+            lines.append(f"\n[{k}]")
+            lines += [f"{sub} = {_toml_repr(val)}" for sub, val in v.items()]
+    return "\n".join(lines) + "\n"
+
+
+def _read_raw(path: Path) -> dict[str, object]:
+    try:
+        return dict(tomllib.loads(path.read_text()))
+    except FileNotFoundError:
+        return {}
+    except OSError as e:
+        raise ConfigError(f"讀不到 {path}：{e}") from None
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{path} 不是合法 TOML：{e}") from None
+
+
+def set_value(key: str, raw_value: str, path: Path | None = None) -> object:
+    """把 ``key = raw_value`` 寫進設定檔，回傳轉型後的值。
+
+    ``colors.<name>`` 點記法寫進 [colors] table（字串值）。其餘鍵須在 ``_SETTERS`` 內，
+    依型別轉換。未知鍵 / 轉型失敗丟 ``ConfigError``（訊息給使用者）。重寫整檔（不保留註解）。
+    """
+    p = path or CONFIG_PATH
+    data = _read_raw(p)
+
+    if "." in key:
+        table, sub = key.split(".", 1)
+        if table != "colors" or not sub:
+            raise ConfigError(f"未知的鍵：{key}")
+        colors = data.get("colors")
+        colors = dict(colors) if isinstance(colors, dict) else {}
+        colors[sub] = raw_value
+        data["colors"] = colors
+        coerced: object = raw_value
+    else:
+        setter = _SETTERS.get(key)
+        if setter is None:
+            raise ConfigError(f"未知的鍵：{key}（可設：{', '.join(_SETTERS)}）")
+        coerced = setter(raw_value)
+        data[key] = coerced
+
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(dump_toml(data))
+    get_config.cache_clear()  # 同 process 內讓下次 get_config() 讀到新值
+    return coerced

ring/focus/__init__.py

@@ -0,0 +1,65 @@
+"""把焦點跳到 session 所在的終端——可插拔、不綁特定 vendor。
+
+每個終端是一個 ``Focuser``（見 ``base.Focuser``）：core 不認識任何具體終端，
+只依序問每個 focuser「這個 session 歸不歸你管」。要支援新終端＝寫一個模組、
+``register_focuser()`` 註冊，core 零改動。內建：tmux / iTerm2 / Terminal.app。
+"""
+
+from __future__ import annotations
+
+from ring.config import get_config
+from ring.focus.base import Focuser
+from ring.focus.iterm2 import focuser as _iterm2
+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` 覆寫。
+_BUILTIN: dict[str, Focuser] = {"tmux": _tmux, "iTerm2": _iterm2, "Terminal": _terminal}
+
+
+def _initial_focusers() -> list[Focuser]:
+    order = get_config().focusers
+    if order:
+        return [_BUILTIN[name] for name in order if name in _BUILTIN]
+    return list(_BUILTIN.values())
+
+
+_FOCUSERS: list[Focuser] = _initial_focusers()
+
+
+def register_focuser(focuser: Focuser, *, first: bool = False) -> None:
+    """外部擴充入口：註冊一個自訂 focuser（first=True 插到最前、優先嘗試）。"""
+    if first:
+        _FOCUSERS.insert(0, focuser)
+    else:
+        _FOCUSERS.append(focuser)
+
+
+def focusers() -> list[Focuser]:
+    """目前已註冊的 focuser，順序即嘗試順序。"""
+    return list(_FOCUSERS)
+
+
+def jump(session: Session) -> tuple[bool, str]:
+    """依序問每個 focuser，誰先接手就用誰。回傳 (成功?, 訊息)。"""
+    if session.status is Status.ENDED:
+        return False, _("已離場的 session 無法跳轉")
+    failures: list[str] = []
+    for focuser in _FOCUSERS:
+        result = focuser.try_focus(session)
+        if result is None:
+            continue
+        ok, msg = result
+        if ok:
+            return True, msg
+        failures.append(f"{focuser.name}: {msg}")
+    if failures:
+        return False, "; ".join(failures)
+    if session.tty:
+        return False, _("找不到這個終端分頁（可能已關閉；刷新後若仍存在，請裝 hook 取得更精準狀態）")
+    return False, _("沒有 focuser 接得住（裝 hook，或一個專案只開一個 session 才測得到 tty）")
+
+
+__all__ = ["Focuser", "focusers", "jump", "register_focuser"]

ring/focus/applescript.py

@@ -0,0 +1,34 @@
+"""用 tty 在 macOS 終端 app 裡找到分頁並聚焦的共用 focuser 基底。
+
+iTerm2 / Terminal.app 共用這套機制（各自提供 AppleScript）；tmux 不走這條、自有實作，
+所以這段「共用實作」放自己的模組，而不是擠進 ``base``（契約）。
+"""
+
+from __future__ import annotations
+
+import shutil
+
+from ring.osascript import osascript
+from ring.registry import Session
+
+
+class AppleScriptTTYFocuser:
+    """用 session 的 tty 在某個 macOS 終端 app 裡找到對應分頁並聚焦。
+
+    各 app 提供自己的 AppleScript（用 ``is running`` 守衛，沒在跑的 app 不會被喚醒）。
+    """
+
+    def __init__(self, app: str, script: str) -> None:
+        self.name = app
+        self._script = script
+
+    def try_focus(self, session: Session) -> tuple[bool, str] | None:
+        tty = session.tty
+        if not tty or not shutil.which("osascript"):
+            return None
+        rc, out, err = osascript(self._script.format(tty=tty))
+        if rc == 0 and out == "ok":
+            return True, f"{self.name} {tty}"
+        if rc == 0 and out == "notfound":
+            return None  # 這個 app 沒有這個 tty → 換下一個 focuser
+        return False, err or out or f"returncode={rc}"

ring/focus/base.py

@@ -0,0 +1,19 @@
+"""Focuser 協定——core 跟具體終端之間的契約（只放 Protocol，不放具體實作）。
+
+``try_focus`` 的回傳語意：
+  None          → 不歸我管（dispatcher 換下一個）
+  (True, msg)   → 我接手且成功
+  (False, err)  → 我接手但失敗（回報原因，不再往下試）
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ring.registry import Session
+
+
+class Focuser(Protocol):
+    name: str
+
+    def try_focus(self, session: Session) -> tuple[bool, str] | None: ...

ring/focus/iterm2.py

@@ -0,0 +1,28 @@
+"""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)

ring/focus/terminal.py

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

ring/focus/tmux.py

@@ -0,0 +1,38 @@
+"""tmux focuser：同一個 tmux server 直接 switch-client 切到那個 pane。"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from ring.registry import Session
+
+
+class TmuxFocuser:
+    name = "tmux"
+
+    def try_focus(self, session: Session) -> tuple[bool, str] | None:
+        target = session.tmux_target
+        if not target or not shutil.which("tmux"):
+            return None
+        tmux_session = target.split(":", 1)[0]
+        window = target.split(".", 1)[0]
+        ok = False
+        last_err = ""
+        for cmd in (
+            ["tmux", "switch-client", "-t", tmux_session],
+            ["tmux", "select-window", "-t", window],
+            ["tmux", "select-pane", "-t", target],
+        ):
+            try:
+                result = subprocess.run(cmd, capture_output=True, text=True, timeout=3)
+            except (OSError, subprocess.SubprocessError) as exc:
+                return False, str(exc)
+            if result.returncode == 0:
+                ok = True
+            else:
+                last_err = result.stderr.strip()
+        return (True, f"tmux {target}") if ok else (False, last_err or "tmux switch failed")
+
+
+focuser = TmuxFocuser()