arkaos 4.31.0 → 4.32.0

package/departments/dev/skills/watch/scripts/setup.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""Setup / preflight for /watch.
+
+Modes:
+  setup.py --check      Silent preflight. Exit 0 if ready, 2/3/4 on failure.
+  setup.py --json       Machine-readable status for Claude to parse.
+  setup.py              Installer. Auto-installs deps, scaffolds .env, marks SETUP_COMPLETE.
+
+Design:
+- Silent on success: --check exits 0 with no output when everything's ready so
+  that /watch doesn't spam "setup is complete" on every turn.
+- Idempotent: re-running the installer is safe — it never clobbers existing
+  keys and only appends missing ones.
+- SETUP_COMPLETE=true in ~/.arkaos/watch.env tells us the user has been
+  through a successful installer run at least once.
+- Never sudo. On macOS, auto-install via brew. Elsewhere, print exact commands.
+- Never write an API key to disk automatically — keys belong in `/arka keys`
+  (~/.arkaos/keys.json); watch.env only carries placeholders as a fallback.
+"""
+from __future__ import annotations
+
+import contextlib
+import json
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+from config import (  # noqa: E402
+    config_file,
+    get_config,
+    read_env_file,
+    resolve_api_key,
+)
+
+REQUIRED_BINARIES = ["ffmpeg", "ffprobe", "yt-dlp"]
+ENV_TEMPLATE = """# ArkaOS /watch configuration
+#
+# Whisper transcription fallback — used only when yt-dlp cannot get captions
+# (or when you point /watch at a local file with no subtitles).
+#
+# PREFERRED: store keys with `/arka keys` (~/.arkaos/keys.json) — this file
+# is only a fallback. Groq runs whisper-large-v3 cheaper and faster; OpenAI
+# whisper-1 is the compatible alternative.
+#
+# Get a Groq key:  https://console.groq.com/keys
+# Get an OpenAI key:  https://platform.openai.com/api-keys
+#
+# With no key anywhere, /watch still works, but videos without native
+# captions come back frames-only.
+
+GROQ_API_KEY=
+OPENAI_API_KEY=
+
+# Default watch behavior (the /watch first-run wizard sets this for you).
+# Allowed values: transcript | efficient | balanced | token-burner
+# Keep the value on its own line with no trailing comment.
+# WATCH_DETAIL=balanced
+"""
+
+
+def _which(name: str) -> str | None:
+    return shutil.which(name)
+
+
+def _binary_runs(name: str) -> bool:
+    """A binary on PATH can still be a corpse — e.g. a dangling homebrew
+    dylib makes ffmpeg abort at load (dyld error, exit 134). Probe
+    `-version` so a broken install is reported as missing instead of
+    crashing mid-run with no setup hint."""
+    try:
+        result = subprocess.run([name, "-version"], capture_output=True, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return result.returncode == 0
+
+
+def _check_binaries() -> list[str]:
+    missing: list[str] = []
+    for b in REQUIRED_BINARIES:
+        if not _which(b):
+            missing.append(b)
+        elif b in ("ffmpeg", "ffprobe") and not _binary_runs(b):
+            # Only probe the native binaries: they are the dyld-breakage
+            # candidates and probe in ~20ms. yt-dlp is a Python zipapp —
+            # probing it costs interpreter startup and breaks the <100ms
+            # --check budget.
+            missing.append(b)
+    return missing
+
+
+_PERM_WARNED: set[str] = set()
+
+
+def _check_file_permissions(path: Path) -> None:
+    """Warn to stderr (once per path per process) if a secrets file is
+    world/group readable."""
+    key = str(path)
+    if key in _PERM_WARNED:
+        return
+    try:
+        mode = path.stat().st_mode
+        if mode & 0o044:
+            _PERM_WARNED.add(key)
+            sys.stderr.write(
+                f"[watch] WARNING: {path} is readable by other users. "
+                f"Run: chmod 600 {path}\n"
+            )
+            sys.stderr.flush()
+    except OSError:
+        pass
+
+
+def _have_api_key() -> tuple[bool, str | None]:
+    cfg = config_file()
+    if cfg.exists():
+        _check_file_permissions(cfg)
+    if resolve_api_key("GROQ_API_KEY"):
+        return True, "groq"
+    if resolve_api_key("OPENAI_API_KEY"):
+        return True, "openai"
+    return False, None
+
+
+def is_first_run() -> bool:
+    """True if the installer hasn't completed successfully yet."""
+    return read_env_file().get("SETUP_COMPLETE") != "true"
+
+
+def _scaffold_env() -> bool:
+    """Create ~/.arkaos/watch.env with placeholders if missing."""
+    cfg = config_file()
+    if cfg.exists():
+        return False
+    cfg.parent.mkdir(parents=True, exist_ok=True)
+    cfg.write_text(ENV_TEMPLATE, encoding="utf-8")
+    with contextlib.suppress(OSError):
+        cfg.chmod(0o600)
+    return True
+
+
+def _write_setup_complete() -> None:
+    """Idempotently append SETUP_COMPLETE=true to watch.env.
+
+    Used only after a fully successful install (deps + key). Future sessions
+    detect this marker to skip wizard-style UI and stay silent.
+    """
+    cfg = config_file()
+    cfg.parent.mkdir(parents=True, exist_ok=True)
+    if cfg.exists():
+        existing = cfg.read_text(encoding="utf-8")
+        for line in existing.splitlines():
+            if line.strip().startswith("SETUP_COMPLETE="):
+                return
+        if existing and not existing.endswith("\n"):
+            existing += "\n"
+        cfg.write_text(existing + "SETUP_COMPLETE=true\n", encoding="utf-8")
+    else:
+        cfg.write_text(ENV_TEMPLATE + "\nSETUP_COMPLETE=true\n", encoding="utf-8")
+    with contextlib.suppress(OSError):
+        cfg.chmod(0o600)
+
+
+def _brew_pkg(missing: list[str]) -> list[str]:
+    pkgs: list[str] = []
+    for bin_name in missing:
+        if bin_name in ("ffmpeg", "ffprobe"):
+            if "ffmpeg" not in pkgs:
+                pkgs.append("ffmpeg")
+        elif bin_name == "yt-dlp":
+            if "yt-dlp" not in pkgs:
+                pkgs.append("yt-dlp")
+        else:
+            pkgs.append(bin_name)
+    return pkgs
+
+
+def _install_macos(missing: list[str]) -> tuple[bool, str]:
+    if _which("brew") is None:
+        return False, (
+            "Homebrew is not installed. Install it from https://brew.sh, then re-run setup. "
+            "Or install manually: `brew install " + " ".join(_brew_pkg(missing)) + "`"
+        )
+    pkgs = _brew_pkg(missing)
+    if not pkgs:
+        return True, "nothing to install"
+    cmd = ["brew", "install", *pkgs]
+    print(f"[setup] running: {' '.join(cmd)}", file=sys.stderr)
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        return False, f"brew install failed with exit code {result.returncode}"
+    return True, f"installed via brew: {', '.join(pkgs)}"
+
+
+def _install_hint_linux(missing: list[str]) -> str:
+    pkgs = _brew_pkg(missing)
+    hints = []
+    if "ffmpeg" in pkgs:
+        hints.append("apt: `sudo apt install ffmpeg` or dnf: `sudo dnf install ffmpeg`")
+    if "yt-dlp" in pkgs:
+        hints.append("`pipx install yt-dlp` (recommended) or `pip install --user yt-dlp`")
+    return "\n  ".join(hints) if hints else "nothing to install"
+
+
+def _install_hint_windows(missing: list[str]) -> str:
+    pkgs = _brew_pkg(missing)
+    hints = []
+    if "ffmpeg" in pkgs:
+        hints.append("winget: `winget install Gyan.FFmpeg`")
+    if "yt-dlp" in pkgs:
+        hints.append("winget: `winget install yt-dlp.yt-dlp` or pip: `pip install --user yt-dlp`")
+    return "\n  ".join(hints) if hints else "nothing to install"
+
+
+def _status() -> dict:
+    """Structured preflight snapshot.
+
+    `status` describes the *ideal* state (a Whisper key is encouraged), so a
+    keyless install still reports `needs_key` on the very first run — that's
+    the agent's cue to encourage adding one.
+
+    `can_proceed` is the operational gate: /watch can run as long as the
+    binaries are present AND the user has either set a key or already finished
+    setup (consciously opting out of Whisper). A keyless user who completed
+    setup is NOT nagged on every call.
+    """
+    missing = _check_binaries()
+    has_key, backend = _have_api_key()
+    setup_complete = not is_first_run()
+
+    if not missing and has_key:
+        status = "ready"
+    elif missing and not has_key:
+        status = "needs_install_and_key"
+    elif missing:
+        status = "needs_install"
+    else:
+        status = "needs_key"
+
+    can_proceed = (not missing) and (has_key or setup_complete)
+
+    cfg = get_config()
+    return {
+        "status": status,
+        "can_proceed": can_proceed,
+        "first_run": not setup_complete,
+        "setup_complete": setup_complete,
+        "missing_binaries": missing,
+        "whisper_backend": backend,
+        "has_api_key": has_key,
+        "config_file": str(config_file()),
+        "watch_detail": cfg["detail"],
+        "platform": platform.system(),
+    }
+
+
+def cmd_check() -> int:
+    """Silent-on-success preflight.
+
+    Exit 0 with no output when /watch can run. A keyless user who already
+    finished setup (SETUP_COMPLETE=true) counts as ready — Whisper is
+    encouraged, not required — so they are never nagged on follow-up calls.
+
+    On a state that blocks /watch, print one actionable line to stderr:
+      2 → binaries missing
+      3 → genuine first run with no API key (encourage one)
+      4 → both missing
+    """
+    s = _status()
+    if s["can_proceed"]:
+        return 0
+
+    parts = []
+    if s["missing_binaries"]:
+        parts.append(f"missing binaries: {', '.join(s['missing_binaries'])}")
+    if not s["has_api_key"] and not s["setup_complete"]:
+        parts.append("no Whisper API key (GROQ_API_KEY or OPENAI_API_KEY)")
+    installer = Path(__file__).resolve()
+    sys.stderr.write(
+        f"[watch] setup incomplete ({'; '.join(parts)}). "
+        f"Run: python3 {installer}\n"
+    )
+    sys.stderr.flush()
+
+    if s["missing_binaries"] and not s["has_api_key"]:
+        return 4
+    if s["missing_binaries"]:
+        return 2
+    return 3
+
+
+def cmd_json() -> int:
+    json.dump(_status(), sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def cmd_install() -> int:
+    missing = _check_binaries()
+    installed_deps = False
+    if missing:
+        system = platform.system()
+        if system == "Darwin":
+            ok, msg = _install_macos(missing)
+            print(f"[setup] {msg}", file=sys.stderr)
+            if not ok:
+                return 2
+            still_missing = _check_binaries()
+            if still_missing:
+                print(
+                    f"[setup] still missing after install: {', '.join(still_missing)}",
+                    file=sys.stderr,
+                )
+                return 2
+            installed_deps = True
+        elif system == "Linux":
+            print("[setup] dependencies missing on Linux — please install:", file=sys.stderr)
+            print("  " + _install_hint_linux(missing), file=sys.stderr)
+            return 2
+        elif system == "Windows":
+            print("[setup] dependencies missing on Windows — please install:", file=sys.stderr)
+            print("  " + _install_hint_windows(missing), file=sys.stderr)
+            return 2
+        else:
+            print(
+                f"[setup] unsupported platform ({system}) for auto-install. Install manually:",
+                file=sys.stderr,
+            )
+            print(f"  missing: {', '.join(missing)}", file=sys.stderr)
+            return 2
+
+    created = _scaffold_env()
+    if created:
+        print(f"[setup] created config: {config_file()}")
+    else:
+        print(f"[setup] config exists: {config_file()}")
+
+    has_key, backend = _have_api_key()
+    if has_key:
+        _write_setup_complete()
+        print(f"[setup] ready. whisper backend: {backend}")
+        if installed_deps:
+            print("[setup] installed dependencies; /watch is fully set up.")
+        return 0
+
+    print("")
+    print("[setup] one step left: add a Whisper API key.")
+    print("")
+    print("  Preferred: store it with `/arka keys` — either:")
+    print("    OPENAI_API_KEY  (whisper-1; get one at platform.openai.com/api-keys)")
+    print("    GROQ_API_KEY    (whisper-large-v3 — cheaper, faster; console.groq.com/keys)")
+    print(f"  Fallback: set the same variable in {config_file()}")
+    print("")
+    print("  Without a key, /watch still works but videos without captions come back frames-only.")
+    return 3
+
+
+def main() -> int:
+    if len(sys.argv) > 1:
+        arg = sys.argv[1]
+        if arg == "--check":
+            return cmd_check()
+        if arg == "--json":
+            return cmd_json()
+    return cmd_install()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/departments/dev/skills/watch/scripts/transcribe.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Parse a WebVTT subtitle file into a clean, timestamped transcript.
+
+YouTube auto-subs emit rolling-duplicate cues (each line appears 2-3 times as it
+scrolls). We dedupe consecutive identical cues and merge their time ranges.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+TS_RE = re.compile(
+    r"(\d{2}):(\d{2}):(\d{2})[.,](\d{3})\s+-->\s+(\d{2}):(\d{2}):(\d{2})[.,](\d{3})"
+)
+TAG_RE = re.compile(r"<[^>]+>")
+
+
+def _to_seconds(h: str, m: str, s: str, ms: str) -> float:
+    return int(h) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000.0
+
+
+def parse_vtt(path: str) -> list[dict]:
+    text = Path(path).read_text(encoding="utf-8", errors="ignore")
+    lines = text.splitlines()
+
+    segments: list[dict] = []
+    i = 0
+    while i < len(lines):
+        match = TS_RE.match(lines[i])
+        if not match:
+            i += 1
+            continue
+
+        start = _to_seconds(*match.groups()[:4])
+        end = _to_seconds(*match.groups()[4:])
+        i += 1
+
+        cue_lines: list[str] = []
+        while i < len(lines) and lines[i].strip():
+            cleaned = TAG_RE.sub("", lines[i]).strip()
+            if cleaned:
+                cue_lines.append(cleaned)
+            i += 1
+
+        cue_text = " ".join(cue_lines).strip()
+        if cue_text:
+            segments.append({"start": round(start, 2), "end": round(end, 2), "text": cue_text})
+        i += 1
+
+    return _dedupe(segments)
+
+
+def _dedupe(segments: list[dict]) -> list[dict]:
+    """Collapse rolling duplicates common in YouTube auto-subs."""
+    out: list[dict] = []
+    for seg in segments:
+        if out and seg["text"] == out[-1]["text"]:
+            out[-1]["end"] = seg["end"]
+            continue
+        if out and seg["text"].startswith(out[-1]["text"] + " "):
+            out[-1]["text"] = seg["text"]
+            out[-1]["end"] = seg["end"]
+            continue
+        out.append(seg)
+    return out
+
+
+def filter_range(
+    segments: list[dict],
+    start_seconds: float | None,
+    end_seconds: float | None,
+) -> list[dict]:
+    """Return segments whose time range overlaps [start, end]."""
+    if start_seconds is None and end_seconds is None:
+        return segments
+    lo = start_seconds if start_seconds is not None else float("-inf")
+    hi = end_seconds if end_seconds is not None else float("inf")
+    return [seg for seg in segments if seg["end"] >= lo and seg["start"] <= hi]
+
+
+def format_transcript(segments: list[dict]) -> str:
+    lines = []
+    for seg in segments:
+        start = int(seg["start"])
+        stamp = f"[{start // 60:02d}:{start % 60:02d}]"
+        lines.append(f"{stamp} {seg['text']}")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("usage: transcribe.py <vtt-path>", file=sys.stderr)
+        raise SystemExit(2)
+    print(format_transcript(parse_vtt(sys.argv[1])))