watch-skill 1.2.0__tar.gz

watch_skill-1.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,35 @@
+{
+  "name": "watch-skill",
+  "owner": {
+    "name": "oxbshw",
+    "url": "https://github.com/oxbshw"
+  },
+  "metadata": {
+    "description": "Give any AI agent the ability to actually watch video.",
+    "version": "1.2.0"
+  },
+  "plugins": [
+    {
+      "name": "watch-skill",
+      "source": ".",
+      "description": "Watch, index, ask, and iterate on video (THE LOOP). Persistent index, self-healing answers, and a local lessons store — Windows/Linux/macOS.",
+      "version": "1.2.0",
+      "author": {
+        "name": "Watch Skill contributors",
+        "url": "https://github.com/oxbshw/watch-skill"
+      },
+      "homepage": "https://github.com/oxbshw/watch-skill",
+      "license": "MIT",
+      "keywords": [
+        "video",
+        "vision",
+        "mcp",
+        "skill",
+        "transcription",
+        "ocr",
+        "the-loop",
+        "youtube"
+      ]
+    }
+  ]
+}

watch_skill-1.2.0/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "watch-skill",
+  "displayName": "Watch Skill",
+  "version": "1.2.0",
+  "description": "Give the agent a video input via Watch Skill: watch, index, ask, and iterate (THE LOOP).",
+  "author": {
+    "name": "Watch Skill contributors",
+    "url": "https://github.com/oxbshw/watch-skill"
+  },
+  "homepage": "https://github.com/oxbshw/watch-skill",
+  "repository": "https://github.com/oxbshw/watch-skill",
+  "license": "MIT",
+  "keywords": ["video", "vision", "mcp", "transcription", "ocr", "the-loop"],
+  "skills": "./skills/",
+  "commands": "./commands/",
+  "mcpServers": "./.mcp.json"
+}

watch_skill-1.2.0/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.gif binary
+*.mp4 binary

watch_skill-1.2.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Every pull request gets a review request automatically, so nothing sits in
+# the queue unnoticed. See CONTRIBUTING.md for the review turnaround.
+* @oxbshw

watch_skill-1.2.0/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# Enabling the Sponsor button takes two steps and this file is only one of
+# them: GitHub Sponsors must also be switched on for the oxbshw account at
+# https://github.com/sponsors — until then the button stays hidden.
+github: [oxbshw]

watch_skill-1.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,37 @@
+name: Bug report
+description: Something broke
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you run, what did you expect, what did you get?
+      placeholder: |
+        watch-skill watch "https://..." failed with ...
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Doctor report
+      description: Paste the FULL output of `watch-skill doctor --json` (it contains no secrets — keys are reported as present/absent only).
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: error
+    attributes:
+      label: Structured error
+      description: If a tool/CLI call failed, paste the `{error, message, fix, details}` JSON it printed.
+      render: json
+  - type: input
+    id: agent
+    attributes:
+      label: Agent / surface
+      placeholder: Claude Code MCP / Cursor / CLI / REST / Python
+  - type: input
+    id: source
+    attributes:
+      label: Video source (if shareable)
+      placeholder: URL or "local file, 34 min, mp4"

watch_skill-1.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Something Watch Skill should do
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What can't your agent do today? Concrete scenario beats abstract capability.
+    validations:
+      required: true
+  - type: textarea
+    id: shape
+    attributes:
+      label: What would it look like?
+      description: A CLI/MCP call you wish existed, or expected output.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options: [acquire, perceive, transcribe, index/search, vision providers, the Loop, surfaces (MCP/CLI/REST), docs]

watch_skill-1.2.0/.github/ISSUE_TEMPLATE/new_agent_support.yml

@@ -0,0 +1,23 @@
+name: New agent support
+description: Get Watch Skill working in another AI agent / IDE
+labels: [agent-support]
+body:
+  - type: input
+    id: agent
+    attributes:
+      label: Agent name + version
+      placeholder: e.g. Zed 0.160, Goose 1.2
+    validations:
+      required: true
+  - type: textarea
+    id: mcp
+    attributes:
+      label: How does it speak MCP (or HTTP)?
+      description: Link its MCP config docs. If it has no MCP, the REST API + OpenAPI spec is the path.
+    validations:
+      required: true
+  - type: textarea
+    id: tried
+    attributes:
+      label: What you tried
+      description: Config you wrote, what connected, what failed. If it worked — paste the working config and we'll add a docs/agents page crediting you.

watch_skill-1.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What
+
+<!-- One paragraph: what changes and why. Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] `uv run pytest -q -m "not network"` is green locally
+- [ ] New behavior has a test (live bugs get a regression test *before* the fix counts)
+- [ ] Errors raised are structured (`code` + `message` + actionable `fix`)
+- [ ] `core/` does not import `surfaces/`
+- [ ] Windows-safe paths (`pathlib`, spaces-in-paths tolerated)
+- [ ] Privacy invariants untouched (video never leaves the machine; cloud STT stays opt-in) — or SECURITY.md updated with reviewer sign-off
+- [ ] Non-obvious decisions logged in `docs/DECISIONS.md`

watch_skill-1.2.0/.github/dependabot.yml

@@ -0,0 +1,41 @@
+version: 2
+updates:
+  # Actions pinned by major tag still move underneath you; a compromised or
+  # abandoned action is the shortest path into a release pipeline that can
+  # publish to PyPI.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: "chore(ci)"
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: "chore(deps)"
+    # One PR per week for the routine bumps; anything that breaks an API gets
+    # its own so the failure is readable.
+    groups:
+      minor-and-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+    ignore:
+      # Pinned deliberately in pyproject with a reason next to each bound.
+      - dependency-name: rich
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: "chore(docker)"

watch_skill-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      # the project-pinned ruff, not a floating uvx latest: local and CI
+      # must agree on import classification
+      - run: uv run --only-group dev ruff check .
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install ffmpeg (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - name: Install ffmpeg (Windows)
+        if: runner.os == 'Windows'
+        run: choco install ffmpeg -y --no-progress
+      - name: Sync dependencies
+        run: uv sync --all-extras
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/ms-playwright
+            ~\AppData\Local\ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+      - name: Cache embedding / whisper models
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/huggingface
+            ci-model-cache
+          key: models-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+      - name: Install Playwright browser + recording ffmpeg (Linux)
+        if: runner.os == 'Linux'
+        run: uv run playwright install --with-deps chromium ffmpeg
+      - name: Install Playwright browser + recording ffmpeg (Windows)
+        if: runner.os == 'Windows'
+        run: uv run playwright install chromium ffmpeg
+      - name: Run the offline suite
+        run: uv run pytest -q -m "not network" --timeout 300
+        env:
+          # keep CI hermetic: no live vision backends, no cloud keys
+          WATCHSKILL_VISION_CHEAP_PROVIDER: anthropic
+          WATCHSKILL_VISION_STRONG_PROVIDER: anthropic
+          FASTEMBED_CACHE_PATH: ci-model-cache

watch_skill-1.2.0/.github/workflows/docker.yml

@@ -0,0 +1,106 @@
+name: Docker
+
+# Publishes ghcr.io/oxbshw/watch-skill. GitHub Container Registry needs no
+# account setup and no secret — GITHUB_TOKEN is enough.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "Dockerfile"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "src/**"
+      - ".github/workflows/docker.yml"
+  release:
+    types: [published]
+  pull_request:
+    paths:
+      - "Dockerfile"
+      - ".github/workflows/docker.yml"
+  workflow_dispatch:
+
+env:
+  IMAGE: ghcr.io/${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      id-token: write      # OIDC identity the provenance attestation is signed with
+      attestations: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      # Pull requests from forks cannot push; build them anyway so a broken
+      # Dockerfile is caught in review rather than on main.
+      - name: Log in to ghcr.io
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Tags and labels
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: ${{ env.IMAGE }}:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      # A pushed image that cannot answer --version is worse than no image.
+      - name: The image must run
+        run: |
+          docker run --rm "${{ env.IMAGE }}:ci" --version
+          docker run --rm "${{ env.IMAGE }}:ci" doctor --no-fix --json > doctor.json || true
+          cat doctor.json
+          docker run --rm "${{ env.IMAGE }}:ci" --help > /dev/null
+
+      # arm64 matters: Apple Silicon is most of the macOS install base, and
+      # running an amd64 image under emulation makes ffmpeg work crawl.
+      - name: Set up QEMU for the arm64 build
+        if: github.event_name != 'pull_request'
+        uses: docker/setup-qemu-action@v3
+
+      - name: Push
+        if: github.event_name != 'pull_request'
+        id: push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: mode=max
+          sbom: true
+
+      # Signs the pushed digest with the workflow's own identity, so anyone
+      # can verify the image came from this repository and no other.
+      - name: Attest the build provenance
+        if: github.event_name != 'pull_request'
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-name: ${{ env.IMAGE }}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true

watch_skill-1.2.0/.github/workflows/install.yml

@@ -0,0 +1,138 @@
+name: Install
+
+# The installers used to carry a "written on Windows, unverified elsewhere"
+# disclaimer. This workflow is what replaced it: every push runs the real
+# scripts on a clean runner for each OS we claim to support.
+
+on:
+  # No path filter on main. A first attempt watched only scripts/ and
+  # pyproject.toml, and then the fix that made the installer work on Linux
+  # and macOS landed in src/watch_skill/health/ — so the run that would have
+  # proved it never fired. What the installer does depends on the engine it
+  # installs, so the whole tree is the trigger.
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - "scripts/**"
+      - "src/watch_skill/health/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/install.yml"
+  schedule:
+    # Installers break from the outside — a new uv, a moved ffmpeg package.
+    # Catch that on a Monday, not from a bug report.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+jobs:
+  posix:
+    name: install.sh (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Lint the script
+        if: runner.os == 'Linux'
+        run: shellcheck scripts/install.sh
+
+      # Run against the checked-out copy rather than curl-ing main, so a PR
+      # tests its own changes.
+      - name: Run the installer
+        run: sh scripts/install.sh
+        env:
+          WATCHSKILL_HOME: ${{ runner.temp }}/watch-skill
+          WATCHSKILL_INSTALL_REF: ${{ github.sha }}
+          WATCHSKILL_INSTALL_LOCAL: "1"
+
+      - name: The CLI must exist and report its version
+        run: |
+          cd "${{ runner.temp }}/watch-skill"
+          uv run watch-skill --version
+          uv run watch-skill --help > /dev/null
+
+      # `|| true` matters: the step runs under `bash -e`, so a failing doctor
+      # would abort before the report it just wrote could be printed — which
+      # hides the one thing worth seeing.
+      - name: Doctor must not fail
+        run: |
+          cd "${{ runner.temp }}/watch-skill"
+          uv run watch-skill doctor --json > doctor.json || true
+          cat doctor.json
+          python - <<'EOF'
+          import json, sys
+          report = json.load(open("doctor.json"))
+          for check in report["checks"]:
+              if check["status"] == "fail":
+                  print(f"::error::doctor {check['name']}: {check['message']}")
+          sys.exit(0 if report["ok"] else 1)
+          EOF
+
+      # `timeout` is GNU coreutils and is not on macOS by default, so the
+      # bound is enforced in the shell instead of by an absent binary.
+      - name: MCP server must start and answer a handshake
+        run: |
+          cd "${{ runner.temp }}/watch-skill"
+          printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ci","version":"0"}}}' \
+            | uv run watch-skill serve > handshake.txt 2>server.log &
+          server=$!
+          for _ in $(seq 1 90); do
+            grep -q '"result"' handshake.txt && break
+            kill -0 "$server" 2>/dev/null || break
+            sleep 1
+          done
+          kill "$server" 2>/dev/null || true
+          wait "$server" 2>/dev/null || true
+          cat server.log
+          grep -q '"result"' handshake.txt
+
+  windows:
+    name: install.ps1 (windows-latest)
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run the installer
+        shell: pwsh
+        run: ./scripts/install.ps1
+        env:
+          WATCHSKILL_HOME: ${{ runner.temp }}\watch-skill
+          WATCHSKILL_INSTALL_REF: ${{ github.sha }}
+          WATCHSKILL_INSTALL_LOCAL: "1"
+
+      - name: The CLI must exist and report its version
+        shell: pwsh
+        run: |
+          Set-Location "${{ runner.temp }}\watch-skill"
+          uv run watch-skill --version
+          uv run watch-skill --help | Out-Null
+
+      - name: Doctor must not fail
+        shell: pwsh
+        run: |
+          Set-Location "${{ runner.temp }}\watch-skill"
+          uv run watch-skill doctor --json | Out-File -Encoding utf8 doctor.json
+          Get-Content doctor.json
+          $report = Get-Content doctor.json -Raw | ConvertFrom-Json
+          if (-not $report.ok) { exit 1 }
+
+  # Proves the claim the README makes about zero-install usage. Runs only
+  # after a release has actually landed on PyPI.
+  uvx:
+    name: uvx from PyPI
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - name: uvx must resolve and run the published package
+        run: uvx --from "watch-skill[standard]" watch-skill --version

watch_skill-1.2.0/.github/workflows/integration.yml

@@ -0,0 +1,30 @@
+name: Integration (network)
+
+# Manual trigger only: hits YouTube/TikTok and (optionally) vision APIs.
+# Run before releases; the offline CI suite is the merge gate.
+on:
+  workflow_dispatch:
+    inputs:
+      skip_stages:
+        description: "Comma list for golden_path --skip (e.g. tiktok,loop)"
+        default: "loop"
+
+jobs:
+  golden-path:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - run: uv sync --all-extras
+      - name: Doctor
+        run: uv run watch-skill doctor
+      - name: Network-marked tests
+        run: uv run pytest -q -m network --timeout 600 || true
+      - name: Golden path (requires a vision key secret)
+        if: ${{ vars.WATCHSKILL_HAS_VISION_KEY == 'true' }}
+        env:
+          WATCHSKILL_OPENROUTER_API_KEY: ${{ secrets.WATCHSKILL_OPENROUTER_API_KEY }}
+        run: uv run python scripts/golden_path.py --skip "${{ inputs.skip_stages }}"

watch_skill-1.2.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - run: uv sync --all-extras
+      - name: Install Playwright browser + recording ffmpeg
+        run: uv run playwright install --with-deps chromium ffmpeg
+      - name: Offline suite must be green
+        run: uv run pytest -q -m "not network" --timeout 300
+        env:
+          WATCHSKILL_VISION_CHEAP_PROVIDER: anthropic
+          WATCHSKILL_VISION_STRONG_PROVIDER: anthropic
+      - name: Build wheel + sdist
+        run: uv build
+      - name: Build the Claude Skill bundle
+        run: |
+          uv run python - <<'EOF'
+          import zipfile
+          from pathlib import Path
+          root = Path("skills/watch")
+          Path("dist").mkdir(exist_ok=True)
+          with zipfile.ZipFile("dist/watch-skill.skill", "w", zipfile.ZIP_DEFLATED) as z:
+              for f in root.rglob("*"):
+                  if f.is_file():
+                      z.write(f, f.relative_to(root))
+          EOF
+      - name: Extract changelog section
+        run: |
+          awk '/^## /{n++} n==1' CHANGELOG.md > release-notes.md || cp CHANGELOG.md release-notes.md
+      - name: GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: release-notes.md
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/watch-skill.skill
+      - name: Keep the built distributions for the publish job
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+
+  # Separate job: trusted publishing needs its own id-token, and a failed
+  # upload must not be able to take the GitHub Release down with it.
+  pypi:
+    needs: release
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      # No token: PyPI verifies this workflow's OIDC identity. The publisher
+      # is configured once at
+      # https://pypi.org/manage/project/watch-skill/settings/publishing/
+      #
+      # The official action rather than `uv publish` because it also signs
+      # PEP 740 attestations, so an installer can verify a wheel was built
+      # by this workflow in this repository and not swapped en route.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+          print-hash: true

watch_skill-1.2.0/.gitignore

@@ -0,0 +1,47 @@
+# Self-managed portable binaries (bootstrapped by `watch-skill doctor`)
+bin/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# Environment / secrets
+.env
+.env.*
+
+# Runtime data (never commit user data)
+*.db
+*.sqlite3
+.watch-skill/
+
+# Test / tool caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+# pytest's summary line does not print in this shell, so counts get read from
+# a junit file — scratch output, never part of the tree
+.pytest-junit.xml
+*.junit.xml
+
+# OS noise
+Thumbs.db
+Desktop.ini
+.DS_Store
+
+# Local assistant / workspace artifacts (never part of the product)
+PROGRESS.md
+CLAUDE.md
+.claude/
+AGENTS.local.md
+*_REPORT.md
+*.session.md
+issues_export.local.json
+
+# Internal notes (never tracked)
+notes.local/
+t.xml
+.agents/