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

yt_tools_cli-0.23.2/.claude-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "yt-tools",
+  "displayName": "yt-tools",
+  "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",
+    "url": "https://github.com/kzntsv-dev"
+  },
+  "homepage": "https://github.com/kzntsv-dev/yt-tools",
+  "repository": "https://github.com/kzntsv-dev/yt-tools",
+  "license": "MIT",
+  "keywords": [
+    "youtube",
+    "transcript",
+    "agent",
+    "claude",
+    "audio-analysis",
+    "fft",
+    "bpm",
+    "iterative",
+    "yt-dlp",
+    "ffmpeg",
+    "librosa"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json"
+}

yt_tools_cli-0.23.2/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: ci
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: pytest (full extras)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # The heavy stacks are installed on purpose: a handful of tests exercise the
+      # real audio pipeline rather than a mock, and a suite that is red on a clean
+      # machine teaches everyone to ignore it. The light-core contract is covered
+      # by the gate job below, which runs without any extra.
+      - name: Install
+        run: pip install -e ".[full,test]"
+      - name: Unit + CLI smoke tests
+        run: pytest -q
+
+  build:
+    name: build (sdist + wheel, publishable metadata)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+      # The release job builds these same artifacts on a tag. Running the build
+      # here too is cheap insurance: a packaging mistake should cost a red CI
+      # run, not a burned version number. v0.23.0 is the case in point — build
+      # green, `twine check` green, and PyPI answered 400 on upload because a
+      # `Requires-Dist` carried a direct reference (`bpm-detector @ git+…`).
+      - name: Build + twine check
+        run: |
+          python -m build
+          python -m twine check dist/*
+      - name: Publishable metadata (no direct refs, no dev-repo meta)
+        run: python scripts/check-metadata.py dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  gate:
+    name: install contract (AC4/AC5)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Runs itself inside python:3.12-slim: core install without extras, once
+      # without ffmpeg and once with a real static one, then checks that `warn`
+      # and `missing` stay machine-distinguishable in one --json payload.
+      - name: Core-install gate
+        run: bash scripts/check-core-install.sh

yt_tools_cli-0.23.2/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: release
+
+# A release is a tag: `git tag v0.23.0 && git push origin v0.23.0`. The version in
+# pyproject.toml must match the tag — publish-check (last job) fails the run when
+# it does not, because a green build is not a published release.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish (must match pyproject.toml)"
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+      # Last line of defence, on the exact artifacts about to be uploaded: the
+      # same check CI runs, because this is the run where a miss costs a version.
+      - name: Publishable metadata
+        run: python scripts/check-metadata.py dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    # No API token anywhere: PyPI trusts this workflow through OIDC. The
+    # environment name must match the trusted publisher configured for the
+    # project on PyPI (`pypi`).
+    environment: pypi
+    permissions:
+      id-token: write # the OIDC token the index exchanges for an upload grant
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  verify:
+    name: verify the release landed
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # The point of the job: "uploaded" and "installable" are different claims.
+      - name: publish-check (is the version people install the version we tagged?)
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          [ -n "$version" ] || version="${{ inputs.version }}"
+          python scripts/publish-check.py --version "$version"

yt_tools_cli-0.23.2/.gitignore

@@ -0,0 +1,23 @@
+# Build and run artifacts
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+yt-cache/
+
+# Development-only paths. They exist in the private development repository and
+# must never appear here: this repository is a curated copy, not the dev tree.
+AGENTS.md
+CLAUDE.md
+.wiki/
+.tasks/
+.brainstorm/
+.archive/
+.mappa
+.mappa-manifest.json
+.pi/
+MEMORY.md
+.mcp.json

yt_tools_cli-0.23.2/CHANGELOG.md

@@ -0,0 +1,251 @@
+# Changelog
+
+All notable changes to yt-tools. Format follows [Keep a Changelog](https://keepachangelog.com/);
+the project uses [Semantic Versioning](https://semver.org/).
+
+The version lives in exactly one place — `pyproject.toml` — and is propagated to
+`.claude-plugin/plugin.json` and the skill frontmatter by `scripts/sync-version.py`.
+Releases before 0.8.0 are summarized only in the git log.
+
+## [Unreleased]
+
+_(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
+> for it, so the first installable version is this one.
+
+### Fixed
+
+- **PyPI rejected the `0.23.0` upload with `400 Can't have direct dependency`.**
+  `[full]` carried `bpm-detector @ git+…` — a PEP 508 direct reference — and PyPI
+  refuses those in `Requires-Dist`. `python -m build` and `twine check` both
+  accept them, so the failure existed only on the tag. `[full]` is now core +
+  `[frames]` + `[audio]`; the plugin hook injects bpm-detector on top of it
+  best-effort, and a PyPI install adds it with `pipx inject yt-tools-cli …`
+  (README, *Installing bpm-detector*). Without it `yt-listen` still runs —
+  librosa-only BPM/key, with the sections it cannot fill marked `n/a`.
+- `[tool.hatch.metadata] allow-direct-references` is gone. It is what let the
+  rejected metadata build at all; with no direct references left it is dead
+  weight, and keeping it off means the next one fails at `python -m build`.
+
+### Added
+
+- `scripts/check-metadata.py`: gates the built artifacts — no direct references
+  in `Requires-Dist`, no dev-repo meta (`AGENTS.md`, `CLAUDE.md`, `.mappa/`,
+  `.wiki/`, `.tasks/`, `.pi/`) inside the wheel or the sdist. It runs in CI and
+  again in the release job, on the exact artifacts about to be uploaded.
+- A `build` job in `ci.yml`: sdist + wheel + `twine check` + the metadata gate on
+  every push. A packaging mistake now costs a red run instead of a version
+  number.
+- The sdist target excludes the dev-repo meta (`AGENTS.md`, `CLAUDE.md`,
+  `.mappa/`, `.mappa-manifest.json`, `.pi/`, `.wiki/`, `.tasks/`). The curated
+  pub tree already drops those files, but a build run in the *dev* tree picked
+  them up — dev's `.gitignore` keeps them on purpose — so `python -m build` from
+  a dev checkout put a canon snapshot into the sdist. The new gate found this on
+  its first run.
+
+## [0.23.0] — 2026-09-13
+
+### Changed
+
+- **The distribution is `yt-tools-cli`.** PyPI refuses `yt-tools`: the name folds
+  into the same similarity class as the existing `yttools`, so the upload is
+  rejected at registration. The project, repository, plugin and every console
+  command stay `yt-tools`, and the import name stays `yt_tools` — only what
+  `pip`/`pipx` resolve changed.
+- Every install hint now names the distribution (`pipx inject yt-tools-cli …`,
+  `pip install 'yt-tools-cli[extra]'`), and `doctor` builds its `next_step` from
+  the same constant as the refusals instead of a second hardcoded copy that would
+  have drifted out of sync.
+
+### Added
+
+- `scripts/publish-check.py`: verifies that a release actually landed on PyPI.
+  "Never landed", "version drift" and "incomplete artifacts" are reported as
+  three different failures with three different fixes.
+- `.github/workflows/release.yml`: tag → build → PyPI by trusted publishing (OIDC,
+  no token on disk), with `publish-check` as the final job — a green build is not
+  a published release.
+
+## [0.22.1] — 2026-09-13
+
+### Fixed
+
+- `scripts/check-pypi-name.py`: documented the staleness of its own input. The
+  names come from the simple index, which is CDN-cached, so a project created
+  minutes ago can still read as "available" — the verdict is a pre-flight, not a
+  report on the last hour. Found live, on the day `yt-tools-cli` was registered.
+
+## [0.21.0] — 2026-09-13
+
+### Added
+
+- PyPI name pre-flight (`scripts/check-pypi-name.py`) reproducing warehouse's
+  `ultranormalize_name` similarity rule against the live index.
+
+## [0.20.0] — 2026-09-13
+
+### Added
+
+- `scripts/check-core-install.sh` — the install contract (AC4/AC5) as a runnable
+  gate for a clean `python:3.12-slim`: core install only, then again with a real
+  static `ffmpeg`; asserts `can_proceed`/`next_step`/exit code on both sides and
+  that `warn` and `missing` stay distinguishable in one `--json` payload. Blocks A
+  and B expect opposite exit codes in one run, so it cannot pass vacuously.
+
+## [0.19.1] — 2026-09-13
+
+### Fixed
+
+- `yt-tools cache list` / `cache prune` on an unreadable cache: named cause and a
+  non-zero exit instead of a traceback (the helper stays strict; the CLI explains).
+- `yt-tools cache list` no longer presents a lower-bound size as an exact total —
+  both the entry and the total line carry the qualifier.
+- `yt-tools doctor`: a dangling symlink in place of `yt-cache` (or of one of its
+  ancestors) is a `warn` with the reason, not an `ok`.
+
+## [0.19.0] — 2026-09-13
+
+### Added
+
+- Public version reader: `yt_tools.__version__` is read from the installed
+  distribution metadata (falling back to `pyproject.toml` in a checkout), resolved
+  lazily — the last hand-maintained version source is gone.
+
+### Fixed
+
+- Coverage gaps found in review around the version reader.
+
+## [0.18.2] — 2026-09-13
+
+### Fixed
+
+- `doctor` and `cache list` survive paths that are not representable in a cp1251
+  console (the Windows default) — output paths are data, not decoration.
+
+## [0.18.1] — 2026-09-13
+
+### Fixed
+
+- `doctor`: an unreadable cache is a `warn` with the reason instead of a crash, and
+  a size that could only be partially counted says so ("lower bound").
+- `doctor --base` pointing at a file (or at a path whose ancestor is a file) is a
+  `warn`, not a silent `ok`.
+- Writability is decided by an actual write probe, not `os.access` (which reads the
+  DOS read-only attribute on Windows and made the check dead on the primary platform).
+
+## [0.18.0] — 2026-09-13
+
+### Added
+
+- Portable skill: harness-neutral install and usage instructions, plus the `doctor`
+  preflight as the documented first step.
+
+## [0.17.0] — 2026-09-12
+
+### Added
+
+- `yt-tools doctor` (`--json`): environment preflight with per-check `status`,
+  report-level `can_proceed` and `next_step`. `warn` never blocks; a missing
+  required binary (`yt-dlp`, `ffmpeg`) does. Nothing is installed or mutated.
+
+## [0.16.0] — 2026-09-12
+
+### Added
+
+- Single source of version truth: `pyproject.toml`, with `scripts/sync-version.py`
+  writing the derived manifests and a guard test failing on divergence.
+
+## [0.15.1] — 2026-09-12
+
+### Fixed
+
+- Extra detection by import probe rather than a package-metadata guess; degradation
+  announced with its own wording instead of a refusal.
+
+## [0.15.0] — 2026-09-12
+
+### Changed
+
+- A flow whose optional stack is missing refuses with the exact install command
+  instead of raising `ImportError`.
+
+## [0.14.0] — 2026-09-12
+
+### Changed
+
+- Light core: `pip install yt-tools` pulls `youtube-transcript-api` and `yt-dlp`
+  only. The heavy stacks moved into `[frames]`, `[audio]` and `[ocr]` extras.
+
+## [0.13.1] — 2026-09-12
+
+### Fixed
+
+- Findings from the umbrella review of the frame-budget cluster.
+
+## [0.13.0] — 2026-09-12
+
+### Added
+
+- A video without subtitles refuses with a named reason instead of an empty file;
+  `yt-watch` gained a frames-only mode.
+
+## [0.12.0] — 2026-09-12
+
+### Added
+
+- Frame budget recorded in the `watch.md` artifact.
+
+## [0.11.0] — 2026-09-11
+
+### Fixed
+
+- Unique frame filenames within the same second.
+
+## [0.10.0] — 2026-09-11
+
+### Added
+
+- Near-duplicate frame dedup: the budget is spent on distinct frames.
+
+## [0.9.0] — 2026-09-11
+
+### Added
+
+- Uniform-sampling fallback when scene detection finds nothing (a static video no
+  longer yields a single frame).
+
+## [0.8.0] — 2026-09-11
+
+### Added
+
+- `--max-frames` ceiling: a video cannot hand back an arbitrary number of frames.

yt_tools_cli-0.23.2/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for looking. yt-tools is a small, opinionated toolkit: nine stateless CLIs
+for agent-driven YouTube watching. The rules below exist to keep it that way.
+
+## Getting set up
+
+```bash
+git clone https://github.com/kzntsv-dev/yt-tools.git
+cd yt-tools
+pip install -e ".[full,test]"   # [full] = frames + audio stacks; [ocr] is separate
+pytest -q
+```
+
+`ffmpeg` and `yt-dlp` are external binaries the tools shell out to; `yt-tools
+doctor` reports what is present and the exact command for what is not.
+
+Two gates are worth knowing before you push:
+
+```bash
+pytest -q                              # unit + CLI smoke (network is mocked)
+bash scripts/check-core-install.sh     # needs docker: the install contract, end to end
+```
+
+## What a change should look like
+
+- **Test first.** A behaviour change comes with a test that fails without it. If
+  you cannot make the test fail on the current code, it is not testing the change.
+  A test that cannot fail (a "guard") is welcome, but say so in its docstring.
+- **Explain the refusal.** Absence of an optional dependency is a message with the
+  exact command, never a traceback. The same goes for a broken environment: report
+  it and exit non-zero.
+- **Say what you know and what you do not.** If a number can only be partially
+  computed, qualify it — an undercount presented as an exact figure is the bug
+  class this project has already been bitten by.
+- **Keep the core light.** Anything heavy belongs in an extra. `pip install
+  yt-tools` must stay a seconds-long install.
+- **Add an entry** to `CHANGELOG.md` under `[Unreleased]`, and bump `version` in
+  `pyproject.toml` (see below).
+
+## Style
+
+- Python 3.10+ syntax, `from __future__ import annotations` at the top.
+- Comments and docstrings explain *why* — ideally with the failure that motivated
+  them. "What" is the code's job.
+- Human-facing output templates stay ASCII: the console may be cp1251 on Windows.
+- Keep output parseable: `--json` where a machine reads it, stable wording where a
+  person does.
+
+## Releases
+
+The version lives in exactly one place — `pyproject.toml`. The derived files are
+written by a script, never by hand:
+
+```bash
+# 1. bump `version` in pyproject.toml
+python scripts/sync-version.py          # plugin.json + skill frontmatter
+python scripts/sync-version.py --check  # what the guard test runs
+# 2. add the CHANGELOG entry, commit, push
+git commit -m "feat(scope): what changed (vX.Y.Z)"
+```
+
+`tests/test_version.py` fails when the sources disagree, so a half-finished bump
+cannot ship.
+
+## Reporting a bug
+
+Include what you ran, what you expected, what happened (the exact message), your
+platform, and the output of `yt-tools doctor`. Issues that reproduce on a bare
+`pip install yt-tools` are the most valuable ones.

yt_tools_cli-0.23.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Kuznetsov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.