@rm0nroe/coach-claw 1.0.6

package/coach/bin/coexistence_check.py

@@ -0,0 +1,129 @@
+"""Detect whether the npm CLI distribution has Coach hooks registered
+in ~/.claude/settings.json, so the plugin's hooks can self-defer.
+
+Plugin distribution only — invoked from plugin/bin/bootstrap.sh BEFORE
+any venv setup or Python entry-point exec, so the check is cheap and
+the defer path is fast.
+
+Why this exists:
+
+    npm CLI registers hooks in settings.json:
+        SessionStart     -> ~/.claude/hooks/coach-session-start.py
+        UserPromptSubmit -> ~/.claude/hooks/coach-user-prompt.py
+
+    Plugin registers hooks in plugin/hooks/hooks.json:
+        SessionStart     -> ${CLAUDE_PLUGIN_ROOT}/hooks/coach-session-start.py
+        UserPromptSubmit -> ${CLAUDE_PLUGIN_ROOT}/hooks/coach-user-prompt.py
+
+    A user with both installs gets 2x SessionStart + 2x UserPromptSubmit
+    fires per event. bank.py runs twice (double XP). Tips render twice.
+    `_assemble_celebrate_block` consumes a marker, plugin then re-reads
+    cleared state — depends on which hook lands first; flaky.
+
+The defer rule (CLI wins) is deliberate: the CLI is the canonical
+provider-agnostic distribution, manages OS-side bits the plugin can't
+reach (launchd cron, statusLine), and was likely installed first by
+the user. Plugin self-disables until the user runs `/coach-claw:switch`.
+
+Exit codes:
+    0  — no CLI hooks detected; plugin should proceed.
+    10 — CLI hooks detected; bootstrap.sh should `exit 0` without
+         exec-ing the wrapped Python entry.
+
+Always exits 0 on error (malformed settings.json, missing file). The
+worst case is double-fire, not a broken hook.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+DEFER_EXIT = 10
+HOOK_SCRIPT_NAMES = ("coach-session-start.py", "coach-user-prompt.py")
+
+
+def _coach_dir() -> Path:
+    """Mirror coach_paths.resolve_coach_dir() — duplicated here to keep
+    this script importable BEFORE the venv exists (and hence before the
+    plugin's bin/ is on sys.path)."""
+    base = os.environ.get("COACH_CONFIG_DIR")
+    if base:
+        return Path(base)
+    return Path.home() / ".claude" / "coach"
+
+
+def _command_points_at_cli(cmd: str, plugin_root: str) -> bool:
+    """A hook command is a CLI hook if it references one of our hook
+    script names AND does NOT live under the plugin's own root.
+    Plugin-self matches return False (those are our own hooks)."""
+    if not any(name in cmd for name in HOOK_SCRIPT_NAMES):
+        return False
+    if plugin_root and plugin_root in cmd:
+        return False
+    return True
+
+
+def _scan_hooks(data: dict, plugin_root: str) -> bool:
+    """Walk settings.json hooks tree; return True if any non-plugin
+    coach hook command is registered."""
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return False
+    for event in ("SessionStart", "UserPromptSubmit"):
+        groups = hooks.get(event) or []
+        if not isinstance(groups, list):
+            continue
+        for grp in groups:
+            if not isinstance(grp, dict):
+                continue
+            for h in (grp.get("hooks") or []):
+                if not isinstance(h, dict):
+                    continue
+                cmd = str(h.get("command", ""))
+                if _command_points_at_cli(cmd, plugin_root):
+                    return True
+    return False
+
+
+def _write_defer_marker() -> None:
+    """Persist a marker so /coach-claw:doctor can surface the deferral.
+    Best-effort — never raises into the bootstrap path."""
+    try:
+        coach_dir = _coach_dir()
+        coach_dir.mkdir(parents=True, exist_ok=True)
+        marker = coach_dir / ".plugin-deferred"
+        payload = {
+            "deferred_at": datetime.now(timezone.utc).isoformat(),
+            "reason": "cli-hooks-detected",
+        }
+        marker.write_text(json.dumps(payload))
+    except Exception:
+        pass
+
+
+def main() -> int:
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    settings_path = Path(
+        os.environ.get("CLAUDE_SETTINGS_PATH")
+        or (Path.home() / ".claude" / "settings.json")
+    )
+    if not settings_path.exists():
+        return 0
+    try:
+        data = json.loads(settings_path.read_text())
+    except Exception:
+        return 0
+    if not isinstance(data, dict):
+        return 0
+    if _scan_hooks(data, plugin_root):
+        _write_defer_marker()
+        return DEFER_EXIT
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/coach/bin/configure.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""coach-claw config — terminal-side entrypoint to user_config.
+
+Three subcommands:
+
+    coach-claw config set [--theme NAME] [--statusline VARIANT] [--elo MIN MAX]
+    coach-claw config preview
+    coach-claw config wizard
+
+Wired up by `npm/coach-claw.js` (case "config" → spawnSync python3
+against this file). Inside Claude Code the equivalent surface is the
+`/config` slash command at `skills/config/SKILL.md` — both write to the
+same `.user_config.json` via `user_config.save()`.
+
+The wizard is intentionally narrow: variant + theme only. ELO range is
+a power-user knob; surface it through `config set --elo MIN MAX`.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Allow `python3 ~/.claude/coach/bin/configure.py …` AND in-repo runs.
+_BIN_DIR = Path(__file__).resolve().parent
+if str(_BIN_DIR) not in sys.path:
+    sys.path.insert(0, str(_BIN_DIR))
+
+import user_config  # noqa: E402
+from statusline_variants import VARIANTS, Glyphs, render  # noqa: E402
+from themes import THEMES, list_themes  # noqa: E402
+
+
+def _sample_glyphs(theme_name: str, level: int = 7) -> Glyphs:
+    """Build a representative `Glyphs` payload for previews. Matches the
+    payload `/config preview` uses so terminal and slash-command output
+    stay visually consistent."""
+    ladder = THEMES.get(theme_name, THEMES["craft"])
+    return Glyphs(
+        level=level,
+        name=ladder[level - 1],
+        elo=1232,
+        session_xp=15,
+        sigil_tier="silver",
+        bar_pct=0.30,
+    )
+
+
+# --- preview --------------------------------------------------------------
+
+def cmd_preview(_args: argparse.Namespace) -> int:
+    """Render every variant × the user's current theme, plus L1/L25/L50
+    sample names per theme. Byte-equivalent to `/config preview` from
+    inside Claude Code."""
+    cfg = user_config.load()
+    sample = _sample_glyphs(cfg["theme"])
+
+    print("STATUSLINE VARIANTS (rendered with your current theme):")
+    for k in VARIANTS:
+        marker = " ← current" if k == cfg["statusline_variant"] else ""
+        print(f"  {k:>8} → {render(k, sample)}{marker}")
+
+    print()
+    print("THEMES (sample L1 / L25 / L50 names):")
+    for name in list_themes():
+        arr = THEMES[name]
+        marker = " ← current" if name == cfg["theme"] else ""
+        print(f"  {name:>13} → {arr[0]} … {arr[24]} … {arr[49]}{marker}")
+    return 0
+
+
+# --- set ------------------------------------------------------------------
+
+def cmd_set(args: argparse.Namespace) -> int:
+    """Apply explicitly-passed flags to the config. Keys not passed stay
+    at their existing value (delegated to `user_config.update()`)."""
+    updates: dict = {}
+    if args.theme is not None:
+        updates["theme"] = args.theme
+    if args.statusline is not None:
+        updates["statusline_variant"] = args.statusline
+    if args.elo is not None:
+        emin, emax = args.elo
+        updates["elo_min"] = emin
+        updates["elo_max"] = emax
+
+    if not updates:
+        print("nothing to do — pass at least one of --theme / --statusline / --elo",
+              file=sys.stderr)
+        print("(or run `coach-claw config preview` to see what's available)",
+              file=sys.stderr)
+        return 1
+
+    try:
+        user_config.update(**updates)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    summary = ", ".join(f"{k}={v}" for k, v in updates.items())
+    print(f"saved: {summary}")
+    print("Open a new Claude Code prompt to see it.")
+    return 0
+
+
+# --- wizard ---------------------------------------------------------------
+
+def _ask_choice(label: str, choices: list[str], current: str) -> str:
+    """Prompt for a value from `choices`, defaulting to `current` on
+    blank input. Re-prompts on invalid input. After 3 invalid tries,
+    falls through with the default to avoid infinite loops in weird
+    terminal contexts."""
+    print()
+    print(f"{label} (current: {current}):")
+    for i, name in enumerate(choices, start=1):
+        marker = "  ←" if name == current else ""
+        print(f"  {i:>2}. {name}{marker}")
+    print(f"  (Enter to keep '{current}')")
+
+    for attempt in range(3):
+        raw = input("> ").strip()
+        if not raw:
+            return current
+        # Numeric pick
+        if raw.isdigit():
+            idx = int(raw)
+            if 1 <= idx <= len(choices):
+                return choices[idx - 1]
+        # Name pick
+        if raw in choices:
+            return raw
+        print(f"  '{raw}' is not a valid choice. Pick a number 1-{len(choices)} or a name from the list.")
+
+    print(f"  (giving up after 3 invalid tries — keeping '{current}')")
+    return current
+
+
+def cmd_wizard(_args: argparse.Namespace) -> int:
+    """Interactive variant + theme picker. TTY-gated; non-interactive
+    invocations get a pointer to `config set` and exit 0."""
+    if not sys.stdin.isatty():
+        print("Wizard requires an interactive terminal.")
+        print("For scripted/CI installs, use:")
+        print("  coach-claw config set --theme ocean --statusline pips")
+        return 0
+
+    cfg = user_config.load()
+
+    # Show the live preview up front so the user has a visual reference
+    # for the choices to come.
+    cmd_preview(_args)
+
+    try:
+        new_variant = _ask_choice(
+            "Pick a statusline variant",
+            list(VARIANTS.keys()),
+            cfg["statusline_variant"],
+        )
+        new_theme = _ask_choice(
+            "Pick a theme (50-name level ladder + celebration banners)",
+            list_themes(),
+            cfg["theme"],
+        )
+    except (KeyboardInterrupt, EOFError):
+        print()
+        print("Wizard cancelled — no changes saved.")
+        return 0
+
+    if new_variant == cfg["statusline_variant"] and new_theme == cfg["theme"]:
+        print()
+        print("No changes — config left untouched.")
+        return 0
+
+    try:
+        user_config.update(
+            statusline_variant=new_variant,
+            theme=new_theme,
+        )
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print()
+    sample = _sample_glyphs(new_theme)
+    print(f"  saved: {render(new_variant, sample)}")
+    print("Open a new Claude Code prompt to see it.")
+    return 0
+
+
+# --- argparse glue --------------------------------------------------------
+
+def _parse_elo(raw: str) -> list[int]:
+    """argparse type for `--elo MIN MAX`. Accepts two whitespace-separated
+    ints; argparse runs this for each token with nargs=2."""
+    try:
+        value = int(raw)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"ELO bound must be an integer, got {raw!r}")
+    if value <= 0:
+        raise argparse.ArgumentTypeError(f"ELO bounds must be positive, got {value}")
+    return value
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="coach-claw config",
+        description="Terminal-side editor for ~/.claude/coach/.user_config.json. "
+                    "Same backing file as the /config slash command in Claude Code.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_set = sub.add_parser("set", help="Apply specific values without prompting")
+    p_set.add_argument("--theme", help=f"one of: {', '.join(list_themes())}")
+    p_set.add_argument(
+        "--statusline",
+        help=f"one of: {', '.join(VARIANTS.keys())}",
+    )
+    p_set.add_argument(
+        "--elo",
+        nargs=2,
+        type=_parse_elo,
+        metavar=("MIN", "MAX"),
+        help="ELO interpolation range (default 1000 2800)",
+    )
+    p_set.set_defaults(func=cmd_set)
+
+    p_preview = sub.add_parser(
+        "preview", help="Print every variant × theme combo so you can pick one")
+    p_preview.set_defaults(func=cmd_preview)
+
+    p_wizard = sub.add_parser(
+        "wizard", help="Interactive picker for variant + theme (TTY only)")
+    p_wizard.set_defaults(func=cmd_wizard)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/coach/bin/cron_check.py

@@ -0,0 +1,81 @@
+"""Detect whether the daily Coach insights cron is registered.
+
+Plugin distribution context only — the npm CLI's `coach-claw launchd`
+subcommand is the canonical way to register OS-level scheduling. The
+plugin model has no equivalent (monitors are event-streaming, not
+cron-like). When a user installs only the plugin, profile.yaml never
+gets the daily deterministic refresh and Coach silently grows stale.
+
+This module powers a one-time nudge banner: detect the gap, suggest
+the CLI command, write a marker so we don't re-nudge.
+
+Detection is best-effort and fail-safe — if launchctl/crontab errors
+or times out, we return True (assume registered) so we never harass a
+user with false-positive nudges.
+"""
+from __future__ import annotations
+
+import platform
+import subprocess
+
+
+# Default plist label registered by install-launchd.sh.
+LAUNCHD_LABEL = "com.local.claude-coach"
+
+# Substrings that indicate a Coach cron line on Linux. Matches both the
+# canonical `~/.claude/coach/bin/insights.sh 1d` pattern and the
+# possibly-renamed `claude-coach` script if a future helper introduces
+# one.
+LINUX_CRON_MARKERS = ("claude-coach", "coach/bin/insights.sh")
+
+
+def is_cron_registered() -> bool:
+    """Return True if a Coach insights cron is already registered.
+
+    macOS: queries `launchctl list <LAUNCHD_LABEL>`. Exit 0 means the
+    plist is loaded.
+
+    Linux: greps `crontab -l` for known Coach markers. Empty crontab
+    or grep miss → False.
+
+    Other platforms: returns True (no-op — Windows and other systems
+    don't use the cron path; we don't want to nudge).
+
+    Errors during detection (timeouts, missing binaries) → True. Better
+    to suppress a nudge than to fire a false-positive.
+    """
+    system = platform.system()
+    if system == "Darwin":
+        return _launchctl_loaded(LAUNCHD_LABEL)
+    if system == "Linux":
+        return _crontab_has_coach()
+    return True
+
+
+def _launchctl_loaded(label: str) -> bool:
+    try:
+        r = subprocess.run(
+            ["launchctl", "list", label],
+            capture_output=True,
+            timeout=5,
+        )
+        return r.returncode == 0
+    except Exception:
+        return True  # fail-safe: don't nudge on detection error
+
+
+def _crontab_has_coach() -> bool:
+    try:
+        r = subprocess.run(
+            ["crontab", "-l"],
+            capture_output=True,
+            timeout=5,
+        )
+        # `crontab -l` exits nonzero when the user has no crontab at all.
+        # That's the strongest "not registered" signal we get.
+        if r.returncode != 0:
+            return False
+        out = r.stdout.decode("utf-8", errors="replace")
+        return any(marker in out for marker in LINUX_CRON_MARKERS)
+    except Exception:
+        return True

package/coach/bin/default_statusline.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Render the default Coach Claw statusline composition:
+
+    ◆ <model> ┃ <bar> NN% ┃ <coach segment>
+
+Reads the Claude Code statusline JSON from stdin once and emits a
+single ANSI-colored line on stdout. Replaces an earlier bash wrapper
+that piped through `jq` twice — jq is not in macOS's default PATH,
+so a fresh box rendered `jq: command not found` instead of a model
+name and 0% instead of a bar.
+
+Visual contract — must match what the v0.3.0 bash wrapper rendered:
+
+  • ICE_SILVER ◆ + lowercased model name with " context" stripped and
+    spaces collapsed to "·"
+  • DEEP_COBALT ┃ separator
+  • 20-segment context-window bar with white→cobalt gradient (filled)
+    and DIM_STEEL ▱ (empty); int-clamped 0-100; round-half-up of float
+    percentage
+  • ICE_SILVER NN%
+  • DEEP_COBALT ┃ separator
+  • coach segment from stats.render_segment() (level + ELO + session
+    arrow); rendered in-process — no second Python invocation
+
+The prefix always renders even on a fresh install with no profile;
+the trailing coach segment is silent until stats.py has signal.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from stats import render_segment  # noqa: E402
+
+# Palette — RGB triples match coach/default-statusline-command.sh.
+ICE_SILVER  = "\x1b[38;2;200;214;229m"
+DEEP_COBALT = "\x1b[38;2;30;144;255m"
+DIM_STEEL   = "\x1b[38;2;58;58;74m"
+RESET       = "\x1b[0m"
+
+BAR_SEGMENTS = 20
+
+
+def _normalize_model(display_name: str) -> str:
+    """Lowercase, strip ' context' substrings, collapse spaces to '·'.
+
+    Mirrors `tr '[:upper:]' '[:lower:]' | sed 's/ context//g; s/ /·/g'`
+    from the deleted bash wrapper. Order matters: lowercase first so
+    "Context" matches " context" after casing.
+    """
+    s = display_name.lower().replace(" context", "")
+    return s.replace(" ", "·")
+
+
+def _render_bar(used_int: int) -> str:
+    """20-segment bar with white→cobalt gradient on filled segments."""
+    used_int = max(0, min(100, used_int))
+    filled = used_int * BAR_SEGMENTS // 100
+    empty = BAR_SEGMENTS - filled
+    parts: list[str] = []
+    for i in range(filled):
+        if filled <= 1:
+            t_num, t_den = 0, 1
+        else:
+            t_num, t_den = i, filled - 1
+        # White (#FFFFFF) → DEEP_COBALT (#1E90FF). Integer math matches
+        # bash's `$(( ))` rounding-toward-zero so visual output is
+        # byte-identical to the deleted wrapper for any used_int.
+        r = 255 - (255 - 30)  * t_num // t_den
+        g = 255 - (255 - 144) * t_num // t_den
+        b = 255
+        parts.append(f"\x1b[38;2;{r};{g};{b}m▰{RESET}")
+    parts.extend(f"{DIM_STEEL}▱{RESET}" for _ in range(empty))
+    return "".join(parts)
+
+
+def _read_stdin_payload() -> dict:
+    try:
+        if sys.stdin.isatty():
+            return {}
+        raw = sys.stdin.read()
+        if not raw:
+            return {}
+        data = json.loads(raw)
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _safe_get(d: dict, *path):
+    cur = d
+    for key in path:
+        if not isinstance(cur, dict):
+            return None
+        cur = cur.get(key)
+    return cur
+
+
+def main() -> int:
+    try:
+        payload = _read_stdin_payload()
+
+        raw_name = _safe_get(payload, "model", "display_name")
+        display_name = raw_name if isinstance(raw_name, str) and raw_name else "unknown"
+        model_label = _normalize_model(display_name)
+
+        raw_pct = _safe_get(payload, "context_window", "used_percentage")
+        used_pct = float(raw_pct) if isinstance(raw_pct, (int, float)) else 0.0
+        used_int = max(0, min(100, int(round(used_pct))))
+
+        out = (
+            f"{ICE_SILVER}◆ {model_label}{RESET} {DEEP_COBALT}┃{RESET} "
+            f"{_render_bar(used_int)} {ICE_SILVER}{used_int}%{RESET} "
+            f"{DEEP_COBALT}┃{RESET}"
+        )
+
+        coach = render_segment(payload)
+        if coach:
+            out = f"{out} {coach}"
+
+        sys.stdout.write(out)
+    except Exception:
+        # Failsafe: the statusline runs on every render. A crash here
+        # must not noise up the terminal with a traceback or break
+        # Claude Code's render. Match the hook fail-soft contract —
+        # emit nothing and exit 0; the user's native statusline (or
+        # none) takes over for the next render.
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())