yt-agent 0.3.0__tar.gz

yt_agent-0.3.0/.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.hypothesis
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.tmp-py311
+.tmp-uv-cache
+.uv-cache
+.venv
+__pycache__/
+assets
+dist
+docs
+examples
+output
+tests
+tmp

yt_agent-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: Bug report
+description: Report a reproducible problem in yt-agent
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug. Please include a command, platform, and enough detail to reproduce the issue.
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      placeholder: macOS 15, Ubuntu 24.04, Windows 11
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command
+      description: Paste the exact command you ran.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics
+      description: Include `yt-agent doctor` output and relevant errors. Remove secrets, cookies, and private paths you do not want public.

yt_agent-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security policy
+    url: https://github.com/jvogan/yt-agent/blob/main/SECURITY.md
+    about: Please do not report security vulnerabilities in public issues.

yt_agent-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Suggest an improvement to yt-agent
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Workflow problem
+      description: Describe the user workflow that is awkward or unsupported today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+    validations:
+      required: true
+  - type: textarea
+    id: automation
+    attributes:
+      label: Human or agent use
+      description: Explain whether this is mainly for direct terminal use, coding-agent use, or both.

yt_agent-0.3.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "ci:"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "deps:"

yt_agent-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+
+- what changed
+- why it changed
+
+## Validation
+
+- [ ] `uv run ruff check .`
+- [ ] `uv run pytest`
+- [ ] `uv build`
+
+## Notes
+
+- config or output changes
+- docs changes
+- compatibility or migration concerns

yt_agent-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,109 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - "codex/**"
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  secrets:
+    name: Secret Scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - name: Install gitleaks
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="8.30.0"
+          arch="$(uname -m)"
+          case "$arch" in
+            x86_64)
+              asset="gitleaks_${version}_linux_x64.tar.gz"
+              checksum="79a3ab579b53f71efd634f3aaf7e04a0fa0cf206b7ed434638d1547a2470a66e"
+              ;;
+            aarch64|arm64)
+              asset="gitleaks_${version}_linux_arm64.tar.gz"
+              checksum="b4cbbb6ddf7d1b2a603088cd03a4e3f7ce48ee7fd449b51f7de6ee2906f5fa2f"
+              ;;
+            *)
+              echo "Unsupported runner architecture: $arch"
+              exit 1
+              ;;
+          esac
+
+          mkdir -p "$RUNNER_TEMP/bin"
+          curl -fsSLo "$RUNNER_TEMP/$asset" "https://github.com/gitleaks/gitleaks/releases/download/v${version}/$asset"
+          echo "${checksum}  $RUNNER_TEMP/$asset" | sha256sum -c -
+          tar -xzf "$RUNNER_TEMP/$asset" -C "$RUNNER_TEMP"
+          install -m 0755 "$RUNNER_TEMP/gitleaks" "$RUNNER_TEMP/bin/gitleaks"
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+      - name: Gitleaks
+        run: gitleaks git . --no-banner --redact
+
+  test:
+    name: Test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Hygiene
+        shell: bash
+        run: |
+          blocked_files="$(git ls-files | grep -E '(^|/)\.env(\..+)?$|(^|/)cookies[^/]*\.txt$|\.sqlite3?$|\.db$|\.jsonl$' || true)"
+          if [ -n "$blocked_files" ]; then
+            echo "Tracked files must not include local state or secret-looking artifacts:"
+            echo "$blocked_files"
+            exit 1
+          fi
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@e06108dd0aef18192324c70427afc47652e63a82 # v7.5.0
+      - name: Sync
+        run: uv sync --dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run mypy
+      - name: Test
+        run: uv run pytest --cov --cov-report=term-missing
+      - name: CLI Smoke
+        run: |
+          uv run yt-agent --version
+          uv run yt-agent --help
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        uses: astral-sh/setup-uv@e06108dd0aef18192324c70427afc47652e63a82 # v7.5.0
+      - name: Build distributions
+        run: uv build
+      - name: Check distributions
+        run: uv run --with twine twine check dist/*
+      - name: Install smoke
+        run: |
+          uv tool run --from . yt-agent --help

yt_agent-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+      - name: Build distributions
+        run: uv build
+      - name: Check distributions
+        run: uv run --with twine twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e

yt_agent-0.3.0/.gitignore

@@ -0,0 +1,25 @@
+.pytest_cache/
+.ruff_cache/
+.venv/
+.tmp-py311/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.DS_Store
+coverage.xml
+htmlcov/
+output/
+tmp/
+assets/tmp/
+.env
+.env.*
+cookies.txt
+cookies*.txt
+*.sqlite
+*.sqlite3
+*.db
+*.jsonl
+.claude/
+.hypothesis/

yt_agent-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.0
+    hooks:
+      - id: ruff
+        args:
+          - --fix
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - rich>=14.0.0
+          - textual>=2.1.2
+          - typer>=0.16.0
+        pass_filenames: false
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml

yt_agent-0.3.0/AGENTS.md

@@ -0,0 +1,57 @@
+# yt-agent — Agent Guide
+
+## What this is
+Terminal-first YouTube CLI built on yt-dlp. Search, download, catalog (SQLite+FTS5), clip extraction, Textual TUI.
+
+## Dev commands
+- Install: `uv sync --dev`
+- Run tests: `uv run pytest --cov` (fallback: `python -m pytest --cov`)
+- Lint: `uv run ruff check .` (fallback: `python -m ruff check .`)
+- Type check: `uv run mypy`
+- Build: `uv build`
+
+## Key pattern and convention guide
+
+### SQL safety
+- Always use `?` placeholders for SQL parameters
+- LIKE queries use `ESCAPE '\'`
+- FTS5 queries are sanitized per-token via `_fts_query()` in `catalog.py`
+
+### Security pattern
+- All user-facing text goes through `sanitize_terminal_text()` from `security.py`
+- File permissions: 0o700 dirs, 0o600 files on POSIX
+- URL allowlisting via `ALLOWED_YOUTUBE_HOSTS` in `yt_dlp.py`
+- Subprocess calls are list-based only, never `shell=True`
+
+### CLI convention
+- Every command wraps logic in `_run_guarded()` which catches `YtAgentError`, `sqlite3.Error`, `KeyboardInterrupt`
+- `dict[str, Any]` for JSON payloads in cli.py is intentional — do not replace with TypedDict
+- Exit codes: OK=0, DEPENDENCY=3, INPUT=4, CONFIG=5, EXTERNAL=6, BUSY=7, STORAGE=8, INTERRUPTED=130
+- `operation_lock()` prevents concurrent mutations — acquire for writes, not reads
+
+### Output convention
+- Read commands support `--output table|json|plain`
+- Mutation commands support `--output json`, `--dry-run`, `--quiet`
+- JSON error envelopes: `{schema_version, status, exit_code, error_type, message}`
+
+### Model convention
+- All models are `@dataclass(frozen=True)` — immutable
+- `VideoInfo.from_yt_dlp()` handles coercion from raw yt-dlp JSON
+
+## Areas to watch with extra care
+
+### High risk areas
+- `cli.py` (~2350 lines) is the densest module — be careful with imports and the `_run_guarded` pattern
+- `catalog.py` schema changes must preserve backward compatibility
+- Tests heavily use `monkeypatch.setattr("yt_agent.cli.<name>", ...)` — any symbol moved from cli.py must be re-exported so the monkeypatch path still resolves
+- `_fts_query()` sanitization is security-critical — test adversarial inputs
+- `operation_lock` is flock-based (POSIX) / msvcrt (Windows) — platform-specific behavior
+
+### Build verification
+After any changes, verify the full chain:
+```bash
+uv run ruff check .
+uv run mypy
+uv run pytest --cov
+uv build
+```

yt_agent-0.3.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is inspired by Keep a Changelog, and this project follows pre-1.0 semantic versioning.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-03-14
+
+### Added
+
+- History-level secret scanning in CI with a pinned `gitleaks` CLI install and checksum verification, plus contributor and release-checklist guidance for local secret scans.
+- Audio-only download mode via `--audio` flag on `download` and `grab`, backed by the `audio_format` and `default_mode` config keys.
+- `--fetch-subs` and `--auto-subs` flags on `download` and `grab` to save subtitle files during download.
+- `--from-file FILE` option on `download` for batch URL input from a text file.
+- `yt-agent export` and `yt-agent import` for catalog portability.
+- `yt-agent history` to inspect recent manifest-backed downloads.
+- `yt-agent cleanup` to remove orphaned subtitle cache directories, empty channel directories, and leftover `.part` files.
+- `yt-agent library channels` to list distinct channels in the catalog.
+- `yt-agent library playlists` to list indexed playlists with video counts.
+- `yt-agent library remove` to delete videos from the catalog by ID.
+- `yt-agent config validate` to check a config file for errors.
+- Shell completion setup support, `--verbose` / `-v` CLI logging, a TUI search/filter bar, and config environment variable overrides.
+- Timestamped YouTube URLs (`?t=NNN`) in clip search and show output.
+
+### Changed
+
+- Enabled SQLite WAL mode for the catalog to reduce contention during local mutations.
+- Upgraded library search from `LIKE` matching to FTS5-backed queries for faster catalog browsing.
+- Expanded architecture documentation with module roles and end-to-end data-flow diagrams.
+- Polished package metadata and PyPI release readiness for the `0.3.x` line.
+
+### Fixed
+
+- Replaced fragile `assert`-based validation paths in clip and CLI flows with explicit user-facing errors.
+- Narrowed `grab` lock scope and removed duplicate catalog lookups in clip workflows.
+- Added subprocess timeouts around subtitle sidecar fetches.
+- Pruned stale subtitle cache directories when removing catalog entries.
+
+### CI
+
+- Added a tag-triggered PyPI release workflow.
+- Reworked CI with separate lint and security stages, expanded macOS coverage in the test matrix, Codecov uploads, and stricter build ordering.
+- Raised the coverage floor to 85%, expanded property-based and module coverage, and enabled broader Ruff rule sets.
+
+### Documentation
+
+- Expanded command reference, architecture, support-matrix, troubleshooting, workflow, recipe, and release-checklist docs.
+- Improved getting-started guidance for shell completions and environment-driven configuration.
+- Added broader module docstrings across the public API surface.
+
+## [0.2.0] - 2026-03-09
+
+### Added
+
+- Public-readiness docs for getting started, concepts, and agent workflows.
+- Public community files including contributing, security, support, code of conduct, issue templates, and a PR template.
+- `yt-agent --version`, `yt-agent config init`, and `yt-agent config path`.
+- `--output table|json|plain` for read-oriented commands.
+- `--select 1,3` for non-interactive search and playlist selection.
+- `yt-agent library stats`.
+- Cross-platform local-media opening in the TUI.
+
+### Changed
+
+- Lowered the supported Python floor to 3.11.
+- Expanded CI to a multi-platform, multi-Python matrix and added distribution build checks.
+- Reworked the README around quickstart, golden paths, support matrix, and responsible-use guidance.
+- Clarified that the TUI is a read-mostly catalog browser.
+- Shipped `youtube-cli` as a transitional alias for the `0.2.x` line (removed in `0.3.x`).
+
+### Removed
+
+- The duplicate sample config file. `config/config.sample.toml` is now the single canonical example.
+
+## [0.1.0] - 2026-03-08
+
+### Added
+
+- Initial private release of `yt-agent` with terminal search, download, catalog, clip, and TUI workflows.

yt_agent-0.3.0/CODEOWNERS

@@ -0,0 +1 @@
+* @jvogan

yt_agent-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Code of Conduct
+
+This project follows a simple standard: be respectful, be precise, and do not waste other contributors' time.
+
+## Expected Behavior
+
+- discuss technical tradeoffs directly and respectfully
+- focus on reproducible reports and concrete improvements
+- assume good faith unless there is clear evidence otherwise
+
+## Unacceptable Behavior
+
+- harassment, insults, or personal attacks
+- deliberately disruptive behavior
+- sharing private data, credentials, cookies, or personal media without permission
+
+## Enforcement
+
+Project maintainers may remove comments, close issues, or reject contributions that make the project harder to maintain or the discussion unsafe or unproductive.

yt_agent-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Thanks for contributing to `yt-agent`.
+
+## Before You Start
+
+- For larger changes, open an issue or start a discussion in the issue tracker first.
+- Keep the project CLI-first. Agent integrations and docs are welcome, but they should not replace a solid terminal workflow.
+- Do not commit cookies, exported browser sessions, downloaded media, subtitle caches, or personal local state.
+
+## Development Setup
+
+```bash
+uv sync --dev
+uv run ruff check .
+uv run pytest
+uv build
+```
+
+## Pre-commit Hooks
+
+Install `pre-commit` locally, then enable the repository hooks:
+
+```bash
+uv tool install pre-commit
+pre-commit install
+```
+
+To run the full hook suite on demand:
+
+```bash
+pre-commit run --all-files
+```
+
+## Local Security Checks
+
+Run a full-history secret scan before opening a PR or cutting a release:
+
+```bash
+gitleaks git . --no-banner --redact
+```
+
+If `gitleaks` is not installed locally yet, install it first. On macOS:
+
+```bash
+brew install gitleaks
+```
+
+If you want to inspect the current working tree, including untracked files, run:
+
+```bash
+gitleaks dir . --no-banner --redact
+```
+
+## Expectations
+
+- Preserve stable exit codes and documented command behavior.
+- Prefer `--output json` support over table scraping when adding new read-oriented features.
+- Keep docs in sync with command behavior.
+- Add or update tests for user-facing changes.
+- Keep the repo free of cookies, local state files, and secret-like artifacts.
+
+## Pull Requests
+
+- Keep PRs focused.
+- Mention user-visible behavior changes clearly.
+- Call out config, output, or compatibility changes explicitly.
+- If a change affects automation behavior, document the JSON/plain surface.

yt_agent-0.3.0/Dockerfile

@@ -0,0 +1,37 @@
+FROM python:3.12-slim AS builder
+
+ENV PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    UV_LINK_MODE=copy
+
+WORKDIR /app
+
+RUN python -m pip install --upgrade pip uv
+
+COPY LICENSE README.md pyproject.toml ./
+COPY src ./src
+
+RUN uv build
+
+
+FROM python:3.12-slim
+
+ENV PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /work
+
+RUN apt-get update \
+    && apt-get install --yes --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN python -m pip install --upgrade pip \
+    && python -m pip install yt-dlp
+
+COPY --from=builder /app/dist/yt_agent-*.whl /tmp/
+
+RUN python -m pip install /tmp/yt_agent-*.whl \
+    && rm -f /tmp/yt_agent-*.whl
+
+ENTRYPOINT ["yt-agent"]

yt_agent-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Vogan
+
+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.