zeno-cli 0.3.4__py3-none-any.whl

zeno_cli/hook_install.py

@@ -0,0 +1,269 @@
+"""`zeno hook install`: read-merge-write of Claude Code's ``~/.claude/settings.json``.
+
+zeno OWNS this merge. Claude Code does not reliably merge hooks across config
+scopes (open bugs both ways: hooks merge-not-replace and top-level keys
+replace-not-merge), so we read the file, deep-merge our entries, and write it
+back, with three safety rails from the 2026-06-25 distribution research:
+
+  1. A timestamped ``.zeno-bak.<stamp>`` backup before any write.
+  2. A JSON parse error ABORTS (never swallowed): returning ``{}`` on a malformed
+     but present settings.json would truncate the user's real config on write.
+  3. A ``zeno-managed-hook`` marker on every command we add, as a trailing shell
+     comment, so ``zeno hook uninstall`` removes exactly our entries and a
+     re-install is idempotent (no duplicate capture).
+
+See ``docs/ADOPT.md`` and the ``[[zeno-internal-distribution]]`` memory.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# The cc-bridge hook dispatches internally on ``hook_event_name`` from its stdin
+# payload, so the SAME command is registered for each of these five events.
+HOOK_EVENTS: tuple[str, ...] = (
+    "SessionStart",
+    "UserPromptSubmit",
+    "Stop",
+    "Notification",
+    "SessionEnd",
+)
+
+ZENO_MARKER = "zeno-managed-hook"
+DEFAULT_HOOK_COMMAND = "zeno hook run"
+
+# A handler/statusLine is treated as zeno-owned if its command contains any of
+# these. Includes the legacy dotfiles registrations so a first `zeno hook
+# install` MIGRATES them in place instead of duplicating capture.
+_ZENO_SIGNATURES: tuple[str, ...] = (
+    ZENO_MARKER,
+    "zeno hook run",
+    "zeno-cc-bridge",
+    "zeno_cc_bridge",
+    "zeno-hud",
+    "zeno_hud",
+)
+
+
+class HookInstallError(Exception):
+    """Raised when settings.json is unsafe to edit (malformed / wrong shape)."""
+
+
+def default_settings_path() -> Path:
+    """``~/.claude/settings.json``, honoring CLAUDE_CONFIG_DIR if the user set it."""
+    base = os.environ.get("CLAUDE_CONFIG_DIR") or str(Path.home() / ".claude")
+    return Path(base).expanduser() / "settings.json"
+
+
+def _load_settings(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    raw = path.read_text(encoding="utf-8")
+    if not raw.strip():
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise HookInstallError(
+            f"{path} is not valid JSON ({exc}). Refusing to edit it so your real "
+            "config is never truncated. Fix or remove the file, then retry."
+        ) from exc
+    if not isinstance(data, dict):
+        raise HookInstallError(f"{path}: top-level JSON is not an object; refusing to edit.")
+    return data
+
+
+def _command_text(handler: object) -> str:
+    return str(handler.get("command", "")) if isinstance(handler, dict) else ""
+
+
+def _is_zeno_handler(handler: object) -> bool:
+    cmd = _command_text(handler)
+    return any(sig in cmd for sig in _ZENO_SIGNATURES)
+
+
+def _group_is_zeno(group: object) -> bool:
+    return isinstance(group, dict) and any(_is_zeno_handler(h) for h in group.get("hooks", []))
+
+
+def _timestamp() -> str:
+    # microseconds: avoid same-second backup-stamp collisions (a rapid re-install
+    # would otherwise overwrite the prior backup via shutil.copy2).
+    return datetime.now().strftime("%Y%m%dT%H%M%S%f")
+
+
+def _strip_zeno(groups: list) -> list:
+    """Remove zeno-owned HANDLERS from each matcher group, keeping any co-located
+    non-zeno handler, and drop a group only once its hooks list is empty. (Filtering
+    at the group level would delete the whole group, taking a user's hand-co-located
+    handler with it.) Unchanged groups are reused by identity so callers can detect
+    'nothing changed' with ==.
+    """
+    out: list = []
+    for g in groups:
+        if not isinstance(g, dict):
+            out.append(g)
+            continue
+        handlers = g.get("hooks")
+        if isinstance(handlers, list):
+            kept = [h for h in handlers if not _is_zeno_handler(h)]
+            if not kept:
+                continue  # the whole group was zeno-only -> drop it
+            if len(kept) != len(handlers):
+                out.append({**g, "hooks": kept})
+                continue
+        out.append(g)
+    return out
+
+
+def _backup(path: Path, stamp: str) -> Path | None:
+    if not path.exists():
+        return None
+    bak = path.with_name(f"{path.name}.zeno-bak.{stamp}")
+    shutil.copy2(path, bak)
+    return bak
+
+
+def _write(path: Path, data: dict) -> None:
+    # Atomic: write a sibling temp file then os.replace, so a crash mid-write can never
+    # truncate the user's live settings.json (the exact failure this module guards against).
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.zeno-tmp.{os.getpid()}")
+    tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def install(
+    settings_path: Path,
+    *,
+    hook_command: str = DEFAULT_HOOK_COMMAND,
+    statusline_command: str | None = None,
+    force: bool = False,
+    stamp: str | None = None,
+) -> dict:
+    """Write zeno's capture hook (and optionally the statusLine) into settings.json.
+
+    Idempotent: any prior zeno-owned hook group is dropped and re-added, so
+    re-running never duplicates capture and migrates the legacy dotfiles
+    registration. ``statusline_command`` is set only if absent or already
+    zeno-owned, unless ``force`` (statusLine allows just one value).
+    """
+    stamp = stamp or _timestamp()
+    data = _load_settings(settings_path)
+    command = f"{hook_command}  # {ZENO_MARKER}"
+
+    hooks = data.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        raise HookInstallError("settings.json 'hooks' is not an object; refusing to edit.")
+    for event in HOOK_EVENTS:
+        groups = hooks.setdefault(event, [])
+        if not isinstance(groups, list):
+            raise HookInstallError(f"settings.json hooks.{event} is not a list; refusing to edit.")
+        groups[:] = _strip_zeno(groups)
+        groups.append({"matcher": "*", "hooks": [{"type": "command", "command": command}]})
+
+    statusline_action = "unchanged"
+    if statusline_command is not None:
+        existing = data.get("statusLine")
+        if existing and not _is_zeno_handler(existing) and not force:
+            statusline_action = "skipped-existing"
+        else:
+            data["statusLine"] = {
+                "type": "command",
+                "command": f"{statusline_command}  # {ZENO_MARKER}",
+            }
+            statusline_action = "set"
+
+    backup = _backup(settings_path, stamp)
+    _write(settings_path, data)
+    return {
+        "backup": str(backup) if backup else None,
+        "events": list(HOOK_EVENTS),
+        "statusline": statusline_action,
+        "command": command,
+    }
+
+
+def uninstall(settings_path: Path, *, restore: bool = False, stamp: str | None = None) -> dict:
+    """Remove only zeno-owned entries (or ``restore`` the latest backup wholesale)."""
+    stamp = stamp or _timestamp()
+    if restore:
+        baks = sorted(settings_path.parent.glob(f"{settings_path.name}.zeno-bak.*"))
+        if not baks:
+            raise HookInstallError(f"no zeno backup found next to {settings_path} to restore.")
+        latest = baks[-1]
+        shutil.copy2(latest, settings_path)
+        return {"restored_from": str(latest)}
+
+    data = _load_settings(settings_path)
+    removed_events: list[str] = []
+    hooks = data.get("hooks")
+    if isinstance(hooks, dict):
+        for event in list(hooks):
+            groups = hooks[event]
+            if not isinstance(groups, list):
+                continue
+            stripped = _strip_zeno(groups)
+            if stripped != groups:
+                removed_events.append(event)
+            groups[:] = stripped
+            if not groups:
+                del hooks[event]
+        if not hooks:
+            data.pop("hooks", None)
+
+    statusline_removed = False
+    if _is_zeno_handler(data.get("statusLine")):
+        data.pop("statusLine", None)
+        statusline_removed = True
+
+    backup = _backup(settings_path, stamp)
+    _write(settings_path, data)
+    return {
+        "backup": str(backup) if backup else None,
+        "removed_events": removed_events,
+        "statusline_removed": statusline_removed,
+    }
+
+
+def status(settings_path: Path) -> dict:
+    """Report which events are zeno-owned without mutating anything."""
+    data = _load_settings(settings_path)
+    hooks = data.get("hooks") if isinstance(data.get("hooks"), dict) else {}
+    installed = [ev for ev in HOOK_EVENTS if any(_group_is_zeno(g) for g in hooks.get(ev, []))]
+    return {
+        "settings_path": str(settings_path),
+        "events_installed": installed,
+        "all_events_installed": installed == list(HOOK_EVENTS),
+        "statusline_zeno": _is_zeno_handler(data.get("statusLine")),
+    }
+
+
+def _packaged_hook_path() -> Path:
+    from importlib import resources
+
+    return Path(str(resources.files("zeno_cli") / "_hooks" / "cc_bridge.py"))
+
+
+def run() -> int:
+    """Exec the bundled cc-bridge hook, passing stdin through.
+
+    Called by Claude Code on each registered event via ``zeno hook run``. NEVER
+    blocks Claude Code: if the bundled hook can't be located or exec'd, return 0.
+    """
+    try:
+        hook = _packaged_hook_path()
+    except (ModuleNotFoundError, FileNotFoundError, OSError):
+        return 0
+    if not hook.exists():
+        return 0
+    try:
+        os.execv(sys.executable, [sys.executable, str(hook)])
+    except OSError:
+        return 0
+    return 0  # unreachable once execv succeeds

zeno_cli/hud/__init__.py

@@ -0,0 +1 @@
+"""zeno-hud: the Claude Code statusline (read surface) packaged with the CLI."""