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

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

@@ -1,7 +1,7 @@
 {
   "name": "yt-tools",
   "displayName": "yt-tools",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "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.1 → yt_tools_cli-0.23.2}/CHANGELOG.md

@@ -11,6 +11,33 @@ Releases before 0.8.0 are summarized only in the git log.
 
 _(nothing yet)_
 
+## [0.23.2] — 2026-09-13
+
+### Fixed
+
+- `scripts/publish-check.py` no longer reports a false `version drift` seconds
+  after a successful upload. PyPI's *project-level* JSON API is CDN-cached
+  (`cache-control: max-age=900`), so the `verify` job — which runs about five
+  seconds after the publish step — read the previous version and failed the
+  `0.23.1` release run while the release itself was live and complete. The check
+  now asks the *version-scoped* endpoint (`/pypi/<name>/<version>/json`, a URL
+  that cannot be stale) first, and lets the project endpoint only explain. Same
+  failure class as the simple-index cache behind the 0.22.1 preflight note: the
+  source a check adjudicates on has to be one that cannot lag.
+
+### Changed
+
+- The README and the skill lead with the PyPI install instead of the git URL:
+  `pipx install "yt-tools-cli[full]"`, a pinned form
+  (`pipx install "yt-tools-cli[full]==0.23.1"`), and an explicit note that the
+  distribution is `yt-tools-cli` while the project, the repository and every
+  command stay `yt-tools` (import name `yt_tools`).
+- The *changing extras* advice is corrected: `pipx uninstall` and then install,
+  instead of `pipx install --force`. A forced reinstall on an existing venv was
+  observed leaving the new extras half-installed (`scenedetect` skipped entirely)
+  and resolving `librosa` 1.0 past its cap; `pipx runpip yt-tools-cli list` is
+  the check that sees it.
+
 ## [0.23.1] — 2026-09-13
 
 > `0.23.0` never reached PyPI: the upload was rejected and no artifact exists

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: yt-tools-cli
-Version: 0.23.1
+Version: 0.23.2
 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
@@ -128,20 +128,44 @@ directory at this repo's `skills/` (or symlink `skills/using-yt-tools` into it).
 
 ### Standalone CLI (any environment)
 
-Install directly from this Git repo via [`pipx`](https://pipx.pypa.io/):
+The distribution is **`yt-tools-cli`**: the project, the repository, the plugin and
+every console command stay `yt-tools`, and the import name stays `yt_tools`.
+`pip`/`pipx`/`uv` resolve the distribution name, so that is the one below.
 
 ```bash
 # 1. bootstrap pipx (one-time per user)
 python -m pip install --user pipx
 python -m pipx ensurepath          # adds ~/.local/bin to PATH; restart shell after
 
-# 2. install yt-tools (core) from this repo
-pipx install git+https://github.com/kzntsv-dev/yt-tools.git
+# 2. install from PyPI — core + [frames] + [audio], i.e. every flow except OCR
+pipx install "yt-tools-cli[full]"
 
-# 3. add the extras you need — one combined install re-creates the same venv
-pipx install --force "git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]"
+# reproducible: pin the exact version
+pipx install "yt-tools-cli[full]==0.23.1"
+
+# [ocr] is always separate and explicit (its ONNX model is ~10 MB, fetched lazily)
+pipx inject yt-tools-cli rapidocr onnxruntime
 ```
 
+`uv` users: `uv tool install "yt-tools-cli[full]"`, or for a one-off run
+`uvx --from "yt-tools-cli[full]" yt-transcript <url>`.
+
+**From a checkout instead of PyPI** — the plugin path, or anyone tracking
+`master`:
+
+```bash
+pipx install 'git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]'
+```
+
+> **Changing the extras of an existing install.** `pipx uninstall yt-tools-cli`
+> first, then install the new extras set. `pipx install --force` on an existing
+> venv can leave the new extras half-installed and resolve against the old pin
+> set — observed on a `[full]` reinstall that kept `librosa` 1.0 instead of the
+> capped 0.11 and skipped `scenedetect` entirely. Verify with
+> `pipx runpip yt-tools-cli list`, not by the version alone.
+> `pipx inject yt-tools-cli <packages>` is the narrow alternative when you only
+> need to add packages.
+
 #### What each extra buys you
 
 A plain install is deliberately light: it never pulls OpenCV, librosa or
@@ -176,11 +200,11 @@ pipx inject yt-tools-cli "bpm-detector @ git+https://github.com/libraz/bpm-detec
 Without it `yt-listen` still runs: librosa-only BPM and key, with every section
 it cannot fill marked `n/a` in the markdown rather than silently missing.
 
-> **Adding an extra to an existing pipx venv.** Re-run `pipx install --force`
-> with the full extras list (as in step 3) rather than installing a second
-> time — a plain reinstall of a different extras set replaces the venv. Use
-> `pipx inject yt-tools-cli scenedetect opencv-python` only when you cannot
-> re-run the installer.
+> **Adding a single extra to an existing pipx venv.** `pipx inject yt-tools-cli
+> scenedetect opencv-python` adds packages without rebuilding the venv, which is
+> the cheapest way to widen an install. To change the *extras set* (e.g. move
+> from core to `[full]`), uninstall and reinstall instead — see the note in
+> [Standalone CLI](#standalone-cli-any-environment).
 
 #### What happens when an extra is missing
 

{yt_tools_cli-0.23.1 → yt_tools_cli-0.23.2}/README.md

@@ -86,20 +86,44 @@ directory at this repo's `skills/` (or symlink `skills/using-yt-tools` into it).
 
 ### Standalone CLI (any environment)
 
-Install directly from this Git repo via [`pipx`](https://pipx.pypa.io/):
+The distribution is **`yt-tools-cli`**: the project, the repository, the plugin and
+every console command stay `yt-tools`, and the import name stays `yt_tools`.
+`pip`/`pipx`/`uv` resolve the distribution name, so that is the one below.
 
 ```bash
 # 1. bootstrap pipx (one-time per user)
 python -m pip install --user pipx
 python -m pipx ensurepath          # adds ~/.local/bin to PATH; restart shell after
 
-# 2. install yt-tools (core) from this repo
-pipx install git+https://github.com/kzntsv-dev/yt-tools.git
+# 2. install from PyPI — core + [frames] + [audio], i.e. every flow except OCR
+pipx install "yt-tools-cli[full]"
 
-# 3. add the extras you need — one combined install re-creates the same venv
-pipx install --force "git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]"
+# reproducible: pin the exact version
+pipx install "yt-tools-cli[full]==0.23.1"
+
+# [ocr] is always separate and explicit (its ONNX model is ~10 MB, fetched lazily)
+pipx inject yt-tools-cli rapidocr onnxruntime
 ```
 
+`uv` users: `uv tool install "yt-tools-cli[full]"`, or for a one-off run
+`uvx --from "yt-tools-cli[full]" yt-transcript <url>`.
+
+**From a checkout instead of PyPI** — the plugin path, or anyone tracking
+`master`:
+
+```bash
+pipx install 'git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]'
+```
+
+> **Changing the extras of an existing install.** `pipx uninstall yt-tools-cli`
+> first, then install the new extras set. `pipx install --force` on an existing
+> venv can leave the new extras half-installed and resolve against the old pin
+> set — observed on a `[full]` reinstall that kept `librosa` 1.0 instead of the
+> capped 0.11 and skipped `scenedetect` entirely. Verify with
+> `pipx runpip yt-tools-cli list`, not by the version alone.
+> `pipx inject yt-tools-cli <packages>` is the narrow alternative when you only
+> need to add packages.
+
 #### What each extra buys you
 
 A plain install is deliberately light: it never pulls OpenCV, librosa or
@@ -134,11 +158,11 @@ pipx inject yt-tools-cli "bpm-detector @ git+https://github.com/libraz/bpm-detec
 Without it `yt-listen` still runs: librosa-only BPM and key, with every section
 it cannot fill marked `n/a` in the markdown rather than silently missing.
 
-> **Adding an extra to an existing pipx venv.** Re-run `pipx install --force`
-> with the full extras list (as in step 3) rather than installing a second
-> time — a plain reinstall of a different extras set replaces the venv. Use
-> `pipx inject yt-tools-cli scenedetect opencv-python` only when you cannot
-> re-run the installer.
+> **Adding a single extra to an existing pipx venv.** `pipx inject yt-tools-cli
+> scenedetect opencv-python` adds packages without rebuilding the venv, which is
+> the cheapest way to widen an install. To change the *extras set* (e.g. move
+> from core to `[full]`), uninstall and reinstall instead — see the note in
+> [Standalone CLI](#standalone-cli-any-environment).
 
 #### What happens when an extra is missing
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "yt-tools-cli"
-version = "0.23.1"
+version = "0.23.2"
 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/scripts/publish-check.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Did the release actually land on PyPI?
+
+A green build is not a published release. ``sched`` learned this the expensive
+way: a wave failed on the ``tsc``/dist step and nobody noticed until an external
+check looked — twice for the same version (their ``scripts/publish-check.mjs``).
+The question "is the version people install the version we tagged?" belongs to a
+machine, and it belongs *after* the upload.
+
+So this runs after the publish step and answers three things:
+
+1. does *this* version exist on the index at all ("never landed" — a 404 body);
+2. is its artifact set complete (a release that landed half-built is not a
+   release);
+3. if it is absent, did something else land instead ("version drift" — the build
+   published another version, or a stale tag).
+
+**Which payload answers which question matters.** The project-level endpoint
+``/pypi/<name>/json`` is CDN-cached (``cache-control: max-age=900``), so seconds
+after a successful upload it still serves the *previous* version — and this check
+runs seconds after a successful upload. Adjudicating on it produced a false
+"version drift" on release 0.23.1 for a release that had landed ([[task:2826]],
+the whole reason this file asks twice). The version-scoped endpoint
+``/pypi/<name>/<version>/json`` is a URL nobody has fetched before, so it cannot
+be stale: it decides. The project endpoint only ever explains.
+
+Exit codes: ``0`` landed · ``1`` not landed / drifted / incomplete · ``2`` the
+check could not run (an unrunnable check is never a pass).
+
+Usage::
+
+    python scripts/publish-check.py                 # version from pyproject.toml
+    python scripts/publish-check.py --version 0.23.1
+    # offline / tests: one file per endpoint
+    python scripts/publish-check.py --json-file version.json --project-json-file project.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+#: The version-scoped endpoint: unique per release, therefore never stale.
+PYPI_VERSION_JSON = "https://pypi.org/pypi/{name}/{version}/json"
+#: The project-scoped endpoint: what `latest` means to a user, and CDN-cached.
+PYPI_PROJECT_JSON = "https://pypi.org/pypi/{name}/json"
+_VERSION_RE = re.compile(r'^version\s*=\s*"([^"]+)"', re.MULTILINE)
+_NAME_RE = re.compile(r'^name\s*=\s*"([^"]+)"', re.MULTILINE)
+
+#: Both artifact kinds a release is expected to ship.
+EXPECTED_KINDS = ("bdist_wheel", "sdist")
+
+NOT_FOUND: dict = {"message": "Not Found"}
+
+
+class CheckError(RuntimeError):
+    """The check could not run (bad fixture, unreachable index, HTTP != 404)."""
+
+
+def read_pyproject(path: Path) -> tuple[str | None, str | None]:
+    """``(name, version)`` from ``pyproject.toml``, or ``(None, None)``."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None, None
+    name = _NAME_RE.search(text)
+    version = _VERSION_RE.search(text)
+    return (name.group(1) if name else None, version.group(1) if version else None)
+
+
+def read_json_file(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise CheckError(f"cannot read {path}: {exc}") from exc
+
+
+def fetch_payload(url: str) -> dict:
+    """The index payload, or ``NOT_FOUND`` when the index says 404.
+
+    A 404 is a *result* (nothing is there), not a broken check — that distinction
+    is the difference between "wait for the upload" and "the check is unusable".
+    """
+    try:
+        with urllib.request.urlopen(url, timeout=60) as response:
+            return json.load(response)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return dict(NOT_FOUND)
+        raise CheckError(f"the index answered {exc.code} for {url}") from exc
+    except (urllib.error.URLError, OSError) as exc:
+        raise CheckError(f"cannot reach the index at {url}: {exc}") from exc
+
+
+def _canonical(name: str) -> str:
+    return name.lower().replace("_", "-")
+
+
+def _project_note(project_payload: dict | None, expected_version: str) -> list[str]:
+    """Explain a lagging project endpoint — never decide with it."""
+    if not project_payload or "info" not in project_payload:
+        return []
+    latest = project_payload["info"].get("version")
+    if not latest or latest == expected_version:
+        return []
+    return [
+        f"  note: the project endpoint still serves {latest} - PyPI's project JSON API is "
+        "CDN-cached (cache-control: max-age=900), so it can lag minutes behind an upload; "
+        "the version endpoint above is the authority"
+    ]
+
+
+def _not_landed(
+    lines: list[str], project_payload: dict | None, expected_version: str
+) -> tuple[int, list[str]]:
+    """Our version is absent — the project endpoint says whether something else landed."""
+    if project_payload and "info" in project_payload:
+        info = project_payload["info"]
+        latest = info.get("version")
+        lines.append(f"  on the project endpoint: {info.get('name', '?')} {latest}")
+        if latest and latest != expected_version:
+            lines.append(f"  verdict: version drift - tagged {expected_version}, installable {latest}")
+            lines.append("  fix    : the upload published another version; check the tag and the build")
+            return 1, lines
+    lines.append("  verdict: never landed - the release is not on the index")
+    lines.append("  fix    : wait for the publish job, or re-run it; the upload itself failed")
+    return 1, lines
+
+
+def check(
+    version_payload: dict,
+    project_payload: dict | None,
+    expected_name: str,
+    expected_version: str,
+) -> tuple[int, list[str]]:
+    lines = [f"publish check: {expected_name} {expected_version}"]
+
+    if "info" not in version_payload:
+        return _not_landed(lines, project_payload, expected_version)
+
+    info = version_payload.get("info", {})
+    published_name = info.get("name", "?")
+    published_version = info.get("version", "?")
+    lines.append(f"  on the version endpoint: {published_name} {published_version}")
+
+    if _canonical(published_name) != _canonical(expected_name):
+        lines.append(f"  verdict: name drift - expected {expected_name!r}, index has {published_name!r}")
+        return 1, lines
+
+    if published_version != expected_version:
+        lines.append(
+            f"  verdict: version drift - tagged {expected_version}, "
+            f"that endpoint serves {published_version}"
+        )
+        lines.append("  fix    : the upload published another version; check the tag and the build")
+        return 1, lines
+
+    kinds = {f.get("packagetype") for f in version_payload.get("urls", [])}
+    missing = [kind for kind in EXPECTED_KINDS if kind not in kinds]
+    if missing:
+        lines.append(f"  artifacts: {', '.join(sorted(k for k in kinds if k)) or 'none'}")
+        lines.append(f"  verdict: incomplete - missing {', '.join(missing)}")
+        lines.append("  fix    : the publish step uploaded a partial release")
+        return 1, lines
+
+    lines.append(f"  artifacts: {', '.join(sorted(k for k in kinds if k))}")
+    lines.extend(_project_note(project_payload, expected_version))
+    lines.append("  verdict: landed - what people install is what we tagged")
+    return 0, lines
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="publish-check",
+        description="Verify that a release landed on PyPI (run after the publish step).",
+    )
+    parser.add_argument("--name", help="distribution name (default: pyproject.toml)")
+    parser.add_argument("--version", help="expected version (default: pyproject.toml)")
+    parser.add_argument("--json-file", type=Path, help="read the version-endpoint payload from a file (offline)")
+    parser.add_argument(
+        "--project-json-file",
+        type=Path,
+        help="read the project-endpoint payload from a file (offline; optional)",
+    )
+    parser.add_argument("--url", help="override the version-endpoint URL")
+    parser.add_argument("--project-url", help="override the project-endpoint URL")
+    args = parser.parse_args(argv)
+
+    pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+    declared_name, declared_version = read_pyproject(pyproject)
+    name = args.name or declared_name
+    version = args.version or declared_version
+    if not name or not version:
+        print(f"error: no name/version in {pyproject} and none given", file=sys.stderr)
+        return 2
+
+    try:
+        if args.json_file is not None:
+            version_payload = read_json_file(args.json_file)
+            project_payload = (
+                read_json_file(args.project_json_file) if args.project_json_file is not None else None
+            )
+        else:
+            version_payload = fetch_payload(
+                args.url or PYPI_VERSION_JSON.format(name=name, version=version)
+            )
+            project_url = args.project_url or PYPI_PROJECT_JSON.format(name=name)
+            try:
+                project_payload = fetch_payload(project_url)
+            except CheckError:
+                # Only needed to *explain* an absent version; a proven landing
+                # must not fail because the advisory probe hiccuped.
+                if "info" in version_payload:
+                    project_payload = None
+                else:
+                    raise
+    except CheckError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    code, lines = check(version_payload, project_payload, name, version)
+    print("\n".join(lines))
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -1,6 +1,6 @@
 ---
 name: using-yt-tools
-version: 0.23.1
+version: 0.23.2
 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.
 ---
 
@@ -133,25 +133,47 @@ binaries).
 
 ### Installing the CLI
 
-Install once per machine — one command, the same in every harness:
+Install once per machine — one command, the same in every harness. The
+**distribution** name is `yt-tools-cli` (the project, repo, plugin and all
+commands stay `yt-tools`; the import name is `yt_tools`):
 
 ```bash
-pipx install git+https://github.com/kzntsv-dev/yt-tools.git
+# from PyPI — core + [frames] + [audio], i.e. every flow except OCR
+pipx install "yt-tools-cli[full]"
+
+# core only (transcript / meta / comments / search / cache)
+pipx install yt-tools-cli
+
+# reproducible: pin the exact version
+pipx install "yt-tools-cli[full]==0.23.1"
 ```
 
-For chord progression + structural analysis in `yt-listen`, add the `[full]`
-extra:
+From a checkout instead of PyPI (the plugin path, or tracking `master`):
 
 ```bash
-pipx install "git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]"
+pipx install 'git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]'
 ```
 
+The `[full]` extra is core + `[frames]` + `[audio]`. Chord progression,
+structural segments and the refined BPM/key in `yt-listen` come from
+`bpm-detector`, which is **not on PyPI** and therefore cannot live in the
+published metadata — the Python package index rejects direct VCS references.
+Add it on top:
+
+```bash
+pipx inject yt-tools-cli "bpm-detector @ git+https://github.com/libraz/bpm-detector@v1.1.0"
+```
+
+Without it `yt-listen` still runs (librosa-only BPM/key, unfilled sections marked
+`n/a`). `[ocr]` is always an explicit extra: `pipx inject yt-tools-cli rapidocr
+onnxruntime`.
+
 Some harnesses do this for you: if your host ships the bundled yt-tools plugin
 (Claude Code does), its `SessionStart` hook pipx-installs the `[full]` set from
-the plugin's own clone on the first session after install — no PyPI
-involvement, and a blocked `[full]` VCS fetch falls back to `[frames,audio]`,
-where every flow except OCR still works. A hook is a convenience, not a
-requirement: the two commands above are the contract.
+the plugin's own clone on the first session after install, then injects
+`bpm-detector` best-effort — a blocked VCS fetch warns and leaves the
+librosa-only path, it never fails the install. A hook is a convenience, not a
+requirement: the commands above are the contract.
 
 ### First run on a machine: `yt-tools doctor`
 
@@ -211,9 +233,10 @@ the optional `[ocr]` extra):
    ```
    python -m pip install --user pipx
    python -m pipx ensurepath                                       # one-time; restart shell after
-   pipx install git+https://github.com/kzntsv-dev/yt-tools.git    # core
-   # For chord progression / structure analysis (optional):
-   # pipx install "git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]"
+   pipx install "yt-tools-cli[full]"                               # core + frames + audio
+   pipx inject yt-tools-cli "bpm-detector @ git+https://github.com/libraz/bpm-detector@v1.1.0"
+   # or from a checkout:
+   pipx install 'git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]'
    ```
    If your host ships the bundled plugin (Claude Code users: install
    `yt-tools@opeitcloc03-claude-plugins`), prefer it — its SessionStart hook

{yt_tools_cli-0.23.1 → yt_tools_cli-0.23.2}/tests/test_publish_check.py

@@ -38,8 +38,8 @@ def _payload(version: str, *, wheel: bool = True, sdist: bool = True) -> str:
     return json.dumps({"info": {"name": "yt-tools-cli", "version": version}, "urls": files})
 
 
-def _write(tmp_path: Path, text: str) -> Path:
-    path = tmp_path / "pypi.json"
+def _write(tmp_path: Path, text: str, name: str = "pypi.json") -> Path:
+    path = tmp_path / name
     path.write_text(text, encoding="utf-8")
     return path
 
@@ -61,12 +61,57 @@ def test_a_landed_release_passes(tmp_path):
 
 
 def test_a_version_that_never_landed_fails_and_names_both_versions(tmp_path):
-    """The failure sched saw twice: build green, registry still on the old one."""
-    proc = _run("--version", "9.9.9", "--json-file", str(_write(tmp_path, _payload("0.22.1"))))
+    """The failure sched saw twice: build green, registry still on the old one.
+
+    Restated for the two-endpoint design: *our* version endpoint 404s (the
+    release is not there) while the project endpoint names another version —
+    which is the actual drift signature.
+    [test-modify: test_a_version_that_never_landed_fails_and_names_both_versions:
+     was `--json-file` carrying the project payload with another version; is the
+     same payload passed as `--project-json-file` next to a 404 version payload;
+     reason: the check now asks the version-scoped endpoint first (it cannot be
+     CDN-stale — task:2826), so "what the index serves" is the project payload
+     and "is our release there" is the version payload]
+    """
+    proc = _run(
+        "--version",
+        "9.9.9",
+        "--json-file",
+        str(_write(tmp_path, '{"message": "Not Found"}', name="version.json")),
+        "--project-json-file",
+        str(_write(tmp_path, _payload("0.22.1"), name="project.json")),
+    )
 
     assert proc.returncode == 1
     assert "9.9.9" in proc.stdout  # what we tagged
     assert "0.22.1" in proc.stdout  # what the world installs
+    assert "drift" in proc.stdout
+
+
+def test_a_stale_project_endpoint_does_not_fail_a_landed_release(tmp_path):
+    """The v0.23.1 incident, pinned as a test ([[task:2826]]).
+
+    PyPI's project-level JSON API is CDN-cached (`cache-control: max-age=900`,
+    `X-Cache: HIT`), so five seconds after a successful upload it still serves
+    the *previous* version — and the `verify` job runs exactly then. Adjudicating
+    on that payload produced a false `version drift` on a release that had
+    landed: the uploaded files were on the index the whole time. The
+    version-scoped endpoint is a URL nobody has fetched before, so it cannot be
+    stale; the project endpoint is only allowed to explain, never to decide.
+    """
+    expected = _pyproject_version()
+    proc = _run(
+        "--json-file",
+        str(_write(tmp_path, _payload(expected), name="version.json")),
+        "--project-json-file",
+        str(_write(tmp_path, _payload("0.0.0"), name="project.json")),
+    )
+
+    assert proc.returncode == 0, proc.stdout + proc.stderr
+    assert "landed" in proc.stdout
+    # Named as a cache note, not as a verdict.
+    assert "0.0.0" in proc.stdout
+    assert "cache" in proc.stdout.lower()
 
 
 def test_a_missing_artifact_kind_fails(tmp_path):
@@ -91,6 +136,21 @@ def test_a_project_that_does_not_exist_yet_is_not_a_mismatch(tmp_path):
     assert "does not exist" in proc.stdout or "never landed" in proc.stdout
 
 
+def test_a_project_endpoint_that_is_also_missing_still_says_never_landed(tmp_path):
+    """Both endpoints 404: the release never landed (no drift to report)."""
+    proc = _run(
+        "--version",
+        "9.9.9",
+        "--json-file",
+        str(_write(tmp_path, '{"message": "Not Found"}', name="version.json")),
+        "--project-json-file",
+        str(_write(tmp_path, '{"message": "Not Found"}', name="project.json")),
+    )
+
+    assert proc.returncode == 1
+    assert "never landed" in proc.stdout
+
+
 def test_the_default_expected_version_is_the_tree_s(tmp_path):
     """No arguments: check what this checkout says it is."""
     proc = _run("--json-file", str(_write(tmp_path, _payload(_pyproject_version()))))

yt_tools_cli-0.23.1/scripts/publish-check.py

@@ -1,142 +0,0 @@
-#!/usr/bin/env python3
-"""Did the release actually land on PyPI?
-
-A green build is not a published release. ``sched`` learned this the expensive
-way: a wave failed on the ``tsc``/dist step and nobody noticed until an external
-check looked — twice for the same version (their ``scripts/publish-check.mjs``).
-The question "is the version people install the version we tagged?" belongs to a
-machine, and it belongs *after* the upload.
-
-So this runs after the publish step and answers three things:
-
-1. does the distribution exist on the index at all ("never landed" — a 404 body);
-2. is its latest version the one this checkout declares ("version drift" — the
-   build published something else, or a stale tag);
-3. are both artifacts there (a release that landed half-built is not a release).
-
-Those are three different failures with three different fixes, so they are
-reported separately. Exit codes: ``0`` landed · ``1`` not landed / drifted /
-incomplete · ``2`` the check could not run (an unrunnable check is never a pass).
-
-Usage::
-
-    python scripts/publish-check.py                 # version from pyproject.toml
-    python scripts/publish-check.py --version 0.23.0
-    python scripts/publish-check.py --json-file fixture.json   # offline / tests
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import sys
-import urllib.error
-import urllib.request
-from pathlib import Path
-
-PYPI_JSON = "https://pypi.org/pypi/{name}/json"
-_VERSION_RE = re.compile(r'^version\s*=\s*"([^"]+)"', re.MULTILINE)
-_NAME_RE = re.compile(r'^name\s*=\s*"([^"]+)"', re.MULTILINE)
-
-#: Both artifact kinds a release is expected to ship.
-EXPECTED_KINDS = ("bdist_wheel", "sdist")
-
-
-def read_pyproject(path: Path) -> tuple[str | None, str | None]:
-    """``(name, version)`` from ``pyproject.toml``, or ``(None, None)``."""
-    try:
-        text = path.read_text(encoding="utf-8")
-    except OSError:
-        return None, None
-    name = _NAME_RE.search(text)
-    version = _VERSION_RE.search(text)
-    return (name.group(1) if name else None, version.group(1) if version else None)
-
-
-def fetch_payload(name: str, url: str | None) -> dict:
-    with urllib.request.urlopen(url or PYPI_JSON.format(name=name), timeout=60) as response:
-        return json.load(response)
-
-
-def check(payload: dict, expected_name: str, expected_version: str) -> tuple[int, list[str]]:
-    lines = [f"publish check: {expected_name} {expected_version}"]
-
-    if "info" not in payload:
-        lines.append("  verdict: does not exist on the index - the release never landed")
-        lines.append("  fix    : wait for the publish job, or re-run it; the upload itself failed")
-        return 1, lines
-
-    info = payload.get("info", {})
-    published_name = info.get("name", "?")
-    published_version = info.get("version", "?")
-    lines.append(f"  on the index: {published_name} {published_version}")
-
-    if published_name.lower().replace("_", "-") != expected_name.lower().replace("_", "-"):
-        lines.append(f"  verdict: name drift - expected {expected_name!r}, index has {published_name!r}")
-        return 1, lines
-
-    if published_version != expected_version:
-        lines.append(f"  verdict: version drift - tagged {expected_version}, installable {published_version}")
-        lines.append("  fix    : the upload published another version; check the tag and the build")
-        return 1, lines
-
-    kinds = {f.get("packagetype") for f in payload.get("urls", [])}
-    missing = [kind for kind in EXPECTED_KINDS if kind not in kinds]
-    if missing:
-        lines.append(f"  artifacts: {', '.join(sorted(k for k in kinds if k)) or 'none'}")
-        lines.append(f"  verdict: incomplete - missing {', '.join(missing)}")
-        lines.append("  fix    : the publish step uploaded a partial release")
-        return 1, lines
-
-    lines.append(f"  artifacts: {', '.join(sorted(k for k in kinds if k))}")
-    lines.append("  verdict: landed - what people install is what we tagged")
-    return 0, lines
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        prog="publish-check",
-        description="Verify that a release landed on PyPI (run after the publish step).",
-    )
-    parser.add_argument("--name", help="distribution name (default: pyproject.toml)")
-    parser.add_argument("--version", help="expected version (default: pyproject.toml)")
-    parser.add_argument("--json-file", type=Path, help="read the index payload from a file (offline)")
-    parser.add_argument("--url", help="override the JSON API URL")
-    args = parser.parse_args(argv)
-
-    pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
-    declared_name, declared_version = read_pyproject(pyproject)
-    name = args.name or declared_name
-    version = args.version or declared_version
-    if not name or not version:
-        print(f"error: no name/version in {pyproject} and none given", file=sys.stderr)
-        return 2
-
-    if args.json_file is not None:
-        try:
-            payload = json.loads(args.json_file.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            print(f"error: cannot read {args.json_file}: {exc}", file=sys.stderr)
-            return 2
-    else:
-        try:
-            payload = fetch_payload(name, args.url)
-        except urllib.error.HTTPError as exc:
-            # A 404 is a *result* (nothing landed), not a broken check.
-            if exc.code == 404:
-                payload = {"message": "Not Found"}
-            else:
-                print(f"error: the index answered {exc.code} for {name}", file=sys.stderr)
-                return 2
-        except (urllib.error.URLError, OSError) as exc:
-            print(f"error: cannot reach the index for {name}: {exc}", file=sys.stderr)
-            return 2
-
-    code, lines = check(payload, name, version)
-    print("\n".join(lines))
-    return code
-
-
-if __name__ == "__main__":
-    sys.exit(main())