yt-tools-cli 0.23.2__tar.gz → 0.24.0__tar.gz

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "yt-tools",
   "displayName": "yt-tools",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "Iterative YouTube watching for agents: clean-markdown transcripts with [mm:ss] anchors, targeted frame extraction, FFT audio analysis (BPM, key, chord progression, spectral features), full-metadata extraction (description, chapters, most-replayed, counts, tags), comment scraping, and OCR over cached frames (RapidOCR PP-OCRv5) for silent-with-text videos. Light core (transcript / metadata / comments / search) with heavy stacks in [frames] and [audio] extras. Bundles the using-yt-tools skill and a SessionStart hook that auto-installs from the plugin's local clone via pipx (default [full] extras, fallback to [frames,audio]) and probes ffmpeg.",
   "author": {
     "name": "Victor Kuznetsov",

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/CHANGELOG.md

@@ -11,6 +11,31 @@ Releases before 0.8.0 are summarized only in the git log.
 
 _(nothing yet)_
 
+## [0.24.0] — 2026-09-13
+
+### Added
+
+- `yt-tools doctor` now names the `bpm-detector` enrichment: a `warn` (never a
+  blocker) with the exact `pipx inject` command. It is not an extra and cannot be
+  one, so nothing else in the report was ever going to mention it — a PyPI
+  install had no way to learn the enrichment existed at all.
+- The plugin hook tops the enrichment up on the "version already matches" path.
+  Both hooks ask the CLI (`doctor`) and inject only what it reports missing, so
+  the hook and the report cannot drift into disagreeing about the environment.
+- A syntax guard for the hook scripts: `bash -n` for the POSIX hook, the
+  PowerShell parser for the Windows one. The content guards assert strings, not
+  grammar — a stray `fi` left behind by a block restructure passed all of them
+  and was caught only by running the hook by hand.
+
+### Fixed
+
+- Moving `bpm-detector` out of `[full]` (0.23.1) left it guaranteed by nothing:
+  the hook injected it only right after a reinstall, so a machine whose VCS fetch
+  had once been blocked by a proxy — or one installed before 0.23.1 — stayed on
+  the librosa-only path for good, and silently. Now every session start checks
+  and repairs it, best-effort: a blocked fetch warns and leaves the install
+  working.
+
 ## [0.23.2] — 2026-09-13
 
 ### Fixed

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: yt-tools-cli
-Version: 0.23.2
+Version: 0.24.0
 Summary: CLI suite for iterative YouTube watching by LLM agents: transcript with [mm:ss] anchors, targeted frame extraction, FFT audio analysis (BPM, key, chord progression, spectral features), and OCR over cached frames for silent-with-text videos.
 Project-URL: Homepage, https://github.com/kzntsv-dev/yt-tools
 Project-URL: Repository, https://github.com/kzntsv-dev/yt-tools

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "yt-tools-cli"
-version = "0.23.2"
+version = "0.24.0"
 description = "CLI suite for iterative YouTube watching by LLM agents: transcript with [mm:ss] anchors, targeted frame extraction, FFT audio analysis (BPM, key, chord progression, spectral features), and OCR over cached frames for silent-with-text videos."
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/scripts/ensure-install.ps1

@@ -24,6 +24,28 @@ function Write-PluginLog {
 # exactly that). It is injected on top of the install instead, best-effort.
 $BpmDetectorSpec = 'bpm-detector @ git+https://github.com/libraz/bpm-detector@v1.1.0'
 
+function Inject-BpmDetector {
+    Invoke-Pipx inject yt-tools-cli $BpmDetectorSpec 2>&1 | ForEach-Object { Write-PluginLog $_ }
+    if ($LASTEXITCODE -ne 0) {
+        Write-PluginLog 'WARN: bpm-detector inject failed (VCS fetch blocked?); yt-listen runs the librosa-only path.'
+    }
+}
+
+# Is the enrichment missing from an otherwise healthy install? Ask the CLI -
+# `doctor` owns the check name and the fix command, so the hook cannot drift
+# into disagreeing with what the agent is told. No CLI found (or an older
+# install): stay quiet and do nothing.
+function Test-BpmDetectorMissing {
+    $ytBin = (Get-Command yt-tools -ErrorAction SilentlyContinue).Source
+    if (-not $ytBin) {
+        $candidate = Join-Path $HOME '.local/bin/yt-tools'
+        if (Test-Path $candidate) { $ytBin = $candidate }
+    }
+    if (-not $ytBin) { return $false }
+    $report = & $ytBin doctor 2>$null
+    return [bool]($report | Select-String -Pattern '^\s*warn\s+enrichment:bpm-detector')
+}
+
 # 0. Resolve plugin root ───────────────────────────────────────────────────
 $PluginRoot = $env:CLAUDE_PLUGIN_ROOT
 if (-not $PluginRoot) {
@@ -171,13 +193,20 @@ if ($needsInstall) {
     # enrichment is chord/structure/BPM refinement, not a flow of its own, and
     # yt-listen already renders the librosa-only path with explicit n/a markers.
     if ($installOk) {
-        Invoke-Pipx inject yt-tools-cli $BpmDetectorSpec 2>&1 | ForEach-Object { Write-PluginLog $_ }
-        if ($LASTEXITCODE -ne 0) {
-            Write-PluginLog 'WARN: bpm-detector inject failed (VCS fetch blocked?); yt-listen runs the librosa-only path.'
-        }
+        Inject-BpmDetector
     }
 }
 
+# 2b. bpm-detector on an already-correct install -----------------------------
+# The enrichment lives outside the install spec, so a version match - the common
+# case on every later session start - never enters the block above, and a machine
+# that once lost the VCS fetch would stay on the librosa-only path forever,
+# silently. Probe and top up instead.
+if (-not $needsInstall -and (Test-BpmDetectorMissing)) {
+    Write-PluginLog 'bpm-detector is missing from an up-to-date install; injecting it.'
+    Inject-BpmDetector
+}
+
 # 3. Probe ffmpeg ──────────────────────────────────────────────────────────
 if (-not (Get-Command ffmpeg -ErrorAction SilentlyContinue)) {
     Write-PluginLog 'ffmpeg not on PATH. Install via winget:'

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/scripts/ensure-install.sh

@@ -23,6 +23,25 @@ log() { printf '[yt-tools] %s\n' "$*" >&2; }
 # exactly that). It is injected on top of the install instead, best-effort.
 BPM_DETECTOR_SPEC="bpm-detector @ git+https://github.com/libraz/bpm-detector@v1.1.0"
 
+inject_bpm_detector() {
+    if ! pipx_run inject yt-tools-cli "${BPM_DETECTOR_SPEC}" >&2; then
+        log "WARN: bpm-detector inject failed (VCS fetch blocked?); yt-listen runs the librosa-only path."
+    fi
+}
+
+# Is the enrichment missing from an otherwise healthy install? Ask the CLI —
+# `doctor` owns the check name and the fix command, so the hook cannot drift
+# into disagreeing with what the agent is told. No CLI on PATH (or an older
+# install): stay quiet and do nothing.
+needs_bpm_detector() {
+    yt_bin="$(command -v yt-tools 2>/dev/null || true)"
+    if [ -z "$yt_bin" ] && [ -x "$HOME/.local/bin/yt-tools" ]; then
+        yt_bin="$HOME/.local/bin/yt-tools"
+    fi
+    [ -n "$yt_bin" ] || return 1
+    "$yt_bin" doctor 2>/dev/null | grep -Eq '^[[:space:]]*warn[[:space:]]+enrichment:bpm-detector'
+}
+
 # 0. Resolve plugin root ───────────────────────────────────────────────────
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
 if [ -z "$PLUGIN_ROOT" ]; then
@@ -135,12 +154,20 @@ if [ "$needs_install" = "true" ]; then
     # enrichment is chord/structure/BPM refinement, not a flow of its own, and
     # yt-listen already renders the librosa-only path with explicit n/a markers.
     if [ "$install_ok" = "true" ]; then
-        if ! pipx_run inject yt-tools-cli "${BPM_DETECTOR_SPEC}" >&2; then
-            log "WARN: bpm-detector inject failed (VCS fetch blocked?); yt-listen runs the librosa-only path."
-        fi
+        inject_bpm_detector
     fi
 fi
 
+# 2b. bpm-detector on an already-correct install ──────────────────────────
+# The enrichment lives outside the install spec, so a version match — the common
+# case on every later session start — never enters the block above, and a machine
+# that once lost the VCS fetch would stay on the librosa-only path forever,
+# silently. Probe and top up instead.
+if [ "$needs_install" = "false" ] && needs_bpm_detector; then
+    log "bpm-detector is missing from an up-to-date install; injecting it."
+    inject_bpm_detector
+fi
+
 # 3. Probe ffmpeg ──────────────────────────────────────────────────────────
 if ! command -v ffmpeg >/dev/null 2>&1; then
     case "$(uname -s 2>/dev/null || echo unknown)" in

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/skills/using-yt-tools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-yt-tools
-version: 0.23.2
+version: 0.24.0
 description: Seven flows for YouTube content. **Discovery-search** (`yt-search`) — query → markdown list of candidate videos via yt-dlp's native ytsearch extractor; the entry point when the user hasn't named a URL yet. **Iterative-watch** (summary / exploration) — transcript with [mm:ss] anchors → pick moments → extract frames. **Targeted-frames** (specific timestamps) — extract frames directly, no transcript. **Audio-analysis** (music FFT) — per timestamp spectrogram + numeric digest (BPM, key, chord progression, harmonic content) via `yt-listen`. **Metadata** (`yt-meta`, free — rides the same yt-dlp call) — description, chapters, most-replayed heatmap, view/like/comment counts, tags, subtitle languages as markdown. **Comments** (`yt-comments`, separate paginated scrape) — top comments + nested replies; capped top-50 by default, costly on viral videos, only on explicit request. **OCR** (`yt-ocr`, silent-with-text fallback) — RapidOCR PP-OCRv5 over cached frames → `[mm:ss]` blocks as a transcript substitute when `yt-transcript` is empty or the video is silent-instructional (burned-in captions, schematic labels, chord matrices). Triggers (mixed RU/EN — same skill serves both audiences) — "find a video about X", "search youtube for X", "find tutorial about X", "найди видео про X", "поищи туториал", "обзор на X youtube", "what's in this video", "video summary", "youtube transcript", "что в ролике", "о чём видео", "show frame at N", "покажи кадр на N", "listen to fragment at N", "послушай момент N", "what's the BPM", "BPM/тональность видео", "analyze audio", "спектрограмма", "video description", "show chapters", "most replayed", "video stats", "что в описании", "покажи главы", "самые пересматриваемые", "top comments", "what are people saying", "комменты под роликом", "топ комментариев", "read text from frames", "OCR this video", "what does the caption say", "extract overlay text", "captions burned in", "прочти текст с кадров", "OCR этого видео", "silent video с текстом", or any youtube.com URL. CLI installed once per machine with pipx (`pipx install 'yt-tools-cli[full]'` adds the audio/chord stack); `yt-tools doctor` is the read-only preflight that names whatever is missing. YouTube-only — for Vimeo / Twitch / local files use other tools.
 ---
 

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/tests/test_doctor.py

@@ -24,7 +24,13 @@ from yt_tools import cache as cache_mod
 from yt_tools import cli as umbrella_cli
 from yt_tools import doctor, extras
 
-FULL_ENV = ("scenedetect", "cv2", "librosa", "matplotlib", "rapidocr", "onnxruntime")
+FULL_ENV = ("scenedetect", "cv2", "librosa", "matplotlib", "rapidocr", "onnxruntime", "bpm_detector")
+
+#: Everything a bare core install has *not* got — the extras plus the one
+#: enrichment that cannot be an extra (not on PyPI, and PyPI rejects direct
+#: references in metadata: release 0.23.0 died on that).
+ENRICHMENT_MODULE = "bpm_detector"
+NO_ENRICHMENT_ENV = tuple(m for m in FULL_ENV if m != ENRICHMENT_MODULE)
 BOTH_BINS = ("yt-dlp", "ffmpeg")
 
 
@@ -695,6 +701,50 @@ def test_ok_report_has_no_next_step(monkeypatch, tmp_path, capsys):
     assert rc == 0
 
 
+# ---- the enrichment that cannot be a package extra --------------------------
+#
+# `bpm-detector` is the difference between librosa-only BPM/key and full chord
+# progression + structure in `yt-listen`, but it is not on PyPI and PyPI rejects
+# PEP 508 direct references in `Requires-Dist` — so it cannot ride `[full]`
+# (release 0.23.0 died on exactly that, [[task:2824]]) and is installed with
+# `pipx inject` instead. Nothing in the install spec guarantees it, so doctor has
+# to name it: without this line a PyPI install has no way to learn the enrichment
+# exists at all. Absent is a `warn` — a feature is lost, nothing is blocked (D6).
+
+
+def test_missing_bpm_detector_is_a_warn_with_the_inject_command(monkeypatch, tmp_path):
+    _only_importable(monkeypatch, *NO_ENRICHMENT_ENV)
+    report = doctor.collect(tmp_path, which=_which(BOTH_BINS), version_info=(3, 12, 1))
+
+    check = _by_name(report)["enrichment:bpm-detector"]
+    assert check.status == "warn"
+    assert check.required is False
+    assert check.fix == extras.BPM_DETECTOR_FIX
+    assert "git+https://github.com/libraz/bpm-detector" in check.fix
+    assert report.can_proceed is True
+
+
+def test_a_present_bpm_detector_is_reported_ok(monkeypatch, tmp_path):
+    _only_importable(monkeypatch, *FULL_ENV)
+    report = doctor.collect(tmp_path, which=_which(BOTH_BINS), version_info=(3, 12, 1))
+    assert _by_name(report)["enrichment:bpm-detector"].status == "ok"
+
+
+def test_the_enrichment_alone_becomes_the_next_step(monkeypatch, tmp_path):
+    """Nothing else wrong: the one command worth running is the enrichment."""
+    _only_importable(monkeypatch, *NO_ENRICHMENT_ENV)
+    report = doctor.collect(tmp_path, which=_which(BOTH_BINS), version_info=(3, 12, 1))
+    assert report.next_step == extras.BPM_DETECTOR_FIX
+
+
+def test_a_missing_extra_outranks_the_enrichment(monkeypatch, tmp_path):
+    """Priority stays: extras first (they unlock whole flows), then the warn."""
+    _only_importable(monkeypatch)
+    report = doctor.collect(tmp_path, which=_which(BOTH_BINS), version_info=(3, 12, 1))
+    assert report.next_step.startswith("pipx inject yt-tools-cli ")
+    assert "git+https" not in report.next_step
+
+
 # ---- human output is the default --------------------------------------------
 
 
@@ -707,7 +757,7 @@ def test_human_output_names_every_check_and_the_next_step(monkeypatch, tmp_path,
     out = capsys.readouterr().out
     assert "missing" in out and "can_proceed: no" in out
     assert "next_step: sudo apt install ffmpeg" in out
-    for name in ("python", "yt-dlp", "ffmpeg", "extra:frames", "extra:audio", "extra:ocr", "cache", "version"):
+    for name in ("python", "yt-dlp", "ffmpeg", "extra:frames", "extra:audio", "extra:ocr", "enrichment:bpm-detector", "cache", "version"):
         assert name in out
     assert rc == 1
 

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/tests/test_packaging.py

@@ -17,6 +17,7 @@ import ast
 import json
 import os
 import re
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -95,6 +96,22 @@ HOOK_BPM_INJECT: dict[str, tuple[str, ...]] = {
     ),
 }
 
+# The self-heal half: the enrichment lives *outside* the install spec, so a
+# version match — the common case on every later session start — skips the
+# install branch entirely and nothing would ever put it back. The hook asks the
+# CLI itself (`doctor`), whose report carries the same check name and the same
+# fix command, so the two cannot drift into disagreeing about what is installed.
+HOOK_BPM_SELFHEAL: dict[str, tuple[str, ...]] = {
+    "ensure-install.sh": (
+        r'command\s+-v\s+yt-tools',
+        r'enrichment:bpm-detector',
+    ),
+    "ensure-install.ps1": (
+        r'Get-Command\s+yt-tools',
+        r'enrichment:bpm-detector',
+    ),
+}
+
 # The extras a hook script must pass to its *actual* pipx call. Patterns, not
 # substrings: the log lines around these commands also mention `[full]` and
 # `[frames,audio]`, so a `in text` check stays green with the command deleted
@@ -483,6 +500,25 @@ def test_hook_injects_bpm_detector_best_effort(script_name):
         )
 
 
+@pytest.mark.parametrize("script_name", HOOK_SCRIPTS)
+def test_hook_tops_up_bpm_detector_when_the_version_already_matches(script_name):
+    """The gap the inject alone leaves open.
+
+    `bpm-detector` cannot be part of `[full]` (it is not on PyPI and PyPI rejects
+    direct references in metadata), so nothing in the install spec guarantees it.
+    The inject above only runs after a reinstall — which happens once, on a
+    version change. Every later session start takes the "version matches" path
+    and would leave a machine that once lost the VCS fetch (corporate proxy) on
+    the librosa-only path forever, quietly. So the hook asks the CLI.
+    """
+    code = _code_lines((ROOT / "scripts" / script_name).read_text(encoding="utf-8"))
+    for pattern in HOOK_BPM_SELFHEAL[script_name]:
+        assert re.search(pattern, code), (
+            f"{script_name}: no self-heal probe for the enrichment (no match for {pattern!r}); "
+            "a version match skips the install branch and the inject with it"
+        )
+
+
 @pytest.mark.parametrize("script_name", HOOK_SCRIPTS)
 def test_hook_pins_bpm_detector_to_the_url_requirement_46_records(script_name):
     """The spec lives in the hook now, so the URL is asserted there — verbatim."""
@@ -492,6 +528,42 @@ def test_hook_pins_bpm_detector_to_the_url_requirement_46_records(script_name):
     )
 
 
+def test_hook_shell_script_parses():
+    """Content guards do not see syntax.
+
+    A stray `fi` (from a restructure that moved a block out of an `if`) passed
+    every regex above and every unit test — the packaging suite asserts strings,
+    not grammar. It surfaced only when the hook was run by hand. `bash -n` is the
+    cheap check that sees it, and it costs milliseconds on every push.
+    """
+    bash = shutil.which("bash")
+    if bash is None:  # pragma: no cover - Windows without Git Bash
+        pytest.skip("no bash on PATH")
+    proc = subprocess.run(
+        [bash, "-n", str(ROOT / "scripts" / "ensure-install.sh")],
+        capture_output=True,
+        text=True,
+    )
+    assert proc.returncode == 0, f"ensure-install.sh does not parse:\n{proc.stderr}"
+
+
+def test_hook_powershell_script_parses():
+    """Same guard for the Windows hook (skipped where no PowerShell exists)."""
+    shell = shutil.which("pwsh") or shutil.which("powershell")
+    if shell is None:  # pragma: no cover - Linux/macOS CI
+        pytest.skip("no PowerShell on PATH")
+    script = str(ROOT / "scripts" / "ensure-install.ps1")
+    parse = (
+        f"$errors = $null; "
+        f"[void][System.Management.Automation.Language.Parser]::ParseFile('{script}', [ref]$null, [ref]$errors); "
+        f"if ($errors.Count) {{ $errors | ForEach-Object {{ Write-Error $_.Message }}; exit 1 }}"
+    )
+    proc = subprocess.run(
+        [shell, "-NoProfile", "-Command", parse], capture_output=True, text=True
+    )
+    assert proc.returncode == 0, f"ensure-install.ps1 does not parse:\n{proc.stderr}"
+
+
 # ---- documentation ----------------------------------------------------------
 
 

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/yt_tools/doctor.py

@@ -213,6 +213,30 @@ def ffmpeg_fix(platform_name: str) -> str:
     return FFMPEG_FIX.get(platform_name, FFMPEG_FIX_FALLBACK)
 
 
+def check_bpm_detector() -> Check:
+    """The one enrichment that cannot be an extra — named anyway.
+
+    It does not go through ``check_extra`` because there is no ``[extra]`` to
+    install: the package is not on PyPI, so its absence is only fixable by
+    ``pipx inject``. For the caller it is the same kind of absence as a missing
+    extra — a feature is lost, nothing is blocked — so it is reported the same
+    way, with the exact command (D6). Without this line a PyPI install has no
+    way to learn the enrichment exists at all.
+    """
+    if extras.module_missing(extras.BPM_DETECTOR_MODULE):
+        return Check(
+            "enrichment:bpm-detector",
+            WARN,
+            "not installed - yt-listen falls back to librosa-only BPM/key",
+            fix=extras.BPM_DETECTOR_FIX,
+        )
+    return Check(
+        "enrichment:bpm-detector",
+        OK,
+        "installed - chord progression + structure in yt-listen",
+    )
+
+
 def check_extra(extra: str) -> Check:
     """Is the heavy stack for one flow importable here (D4's probe, not a spec)?"""
     if extras.extra_available(extra):
@@ -431,6 +455,7 @@ def collect(
             "ffmpeg", fix=ffmpeg_fix(platform_name or sys.platform), which=which
         ),
         *(check_extra(extra) for extra in extras.EXTRA_MODULES),
+        check_bpm_detector(),
         check_cache(cache_root(base)),
         check_version(
             package_version=__version__,

{yt_tools_cli-0.23.2 → yt_tools_cli-0.24.0}/yt_tools/extras.py

@@ -41,6 +41,17 @@ EXTRA_PACKAGES: dict[str, tuple[str, ...]] = {
     "ocr": ("rapidocr", "onnxruntime"),
 }
 
+#: The enrichment that cannot be a package extra. ``bpm-detector`` gives
+#: ``yt-listen`` chord progression, structural segments and a refined BPM/key,
+#: but it is not on PyPI — so it can only be a PEP 508 direct reference, and PyPI
+#: rejects those in ``Requires-Dist`` (release 0.23.0 died on exactly that,
+#: [[task:2824]]). It is therefore installed with ``pipx inject``: by the plugin
+#: hook, or by hand from the README. ``doctor`` names it for the same reason it
+#: names a missing extra — a silent quality drop is worse than a named one (D6).
+BPM_DETECTOR_MODULE = "bpm_detector"
+BPM_DETECTOR_SPEC = "bpm-detector @ git+https://github.com/libraz/bpm-detector@v1.1.0"
+BPM_DETECTOR_FIX = f'pipx inject {DISTRIBUTION} "{BPM_DETECTOR_SPEC}"'
+
 _MISSING = object()