CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

jbaruch/speaker-toolkit

Twelve skills for conference speakers covering rhetoric analysis, talk authoring, deck building and export, CFP submissions, publishing, illustrations, shownotes, screencast production, and vertical shorts, informed by a 113-entry Presentation Patterns taxonomy (83 observable: 64 patterns + 19 antipatterns; 30 unobservable: 21 patterns + 9 antipatterns).

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

check-runtime.pyskills/vault-ingress/scripts/

#!/usr/bin/env python3
"""Check imports and commands in the configured vault-ingress runtime.

The installed plugin does not ship ``pyproject.toml``. This stdlib-only probe
reports whether the interpreter recorded in ``config.python_path`` can import
each lane's modules and find its commands. Versions are pinned in
``pyproject.toml`` and nowhere else. Core failures block ingress. Missing
optional dependencies are reported as degradation unless the caller explicitly
requires that lane. Isolated import faults remain lane-local.
"""

from __future__ import annotations

import argparse
import json
import signal
import shutil
import subprocess
import sys
from pathlib import Path
from typing import Any, Callable, Mapping, TypedDict

from ytdlp_runtime import YtDlpResolutionError, resolve_ytdlp


REPORT_SCHEMA_VERSION = 3
MODULE_PROBE_TIMEOUT_SECONDS = 30
# Probe outcomes that leave the module's presence UNKNOWN rather than answered.
# A timeout is the ordinary one: the configured interpreter can live on a
# network filesystem, where a cold import reads its dependencies over the
# network and a healthy install takes minutes. Measured on a Drive-hosted vault
# venv, `import mlx_whisper` took 568s cold and 1s warm, almost all of it scipy.
UNRESOLVED_PROBE_REASONS = frozenset({"timeout", "probe_start_failure"})
MINIMUM_PYTHON = (3, 10)
LANE_REQUIREMENTS: dict[str, dict[str, dict[str, str]]] = {
    "core": {
        "modules": {"PyYAML": "yaml"},
        "commands": {},
    },
    "pdf": {
        "modules": {"pypdf": "pypdf", "psutil": "psutil"},
        "commands": {},
    },
    # outline_schema.py and the shownotes verifier import these at module load.
    "outline": {
        "modules": {"PyYAML": "yaml", "pydantic": "pydantic"},
        "commands": {},
    },
    "pptx": {
        "modules": {"python-pptx": "pptx", "psutil": "psutil"},
        "commands": {},
    },
    "google-drive": {
        "modules": {"gdown": "gdown"},
        "commands": {},
    },
    "captions": {
        "modules": {
            "youtube-transcript-api": "youtube_transcript_api",
        },
        "commands": {},
    },
    "youtube-download": {
        "modules": {"psutil": "psutil"},
        "commands": {"yt-dlp": "yt-dlp"},
    },
    "whisper": {
        "modules": {"mlx-whisper": "mlx_whisper", "psutil": "psutil"},
        "commands": {"ffmpeg": "ffmpeg", "ffprobe": "ffprobe"},
    },
    "speech-calibration": {
        "modules": {
            "mlx-whisper": "mlx_whisper",
            "huggingface-hub": "huggingface_hub",
            "psutil": "psutil",
        },
        "commands": {"ffmpeg": "ffmpeg", "ffprobe": "ffprobe"},
    },
    "source-media": {
        "modules": {"psutil": "psutil"},
        "commands": {"ffprobe": "ffprobe"},
    },
    "source-video": {
        "modules": {"psutil": "psutil"},
        "commands": {"ffprobe": "ffprobe"},
    },
    "video": {
        "modules": {
            "filelock": "filelock",
            "imagehash": "imagehash",
            "numpy": "numpy",
            "Pillow": "PIL",
        },
        "commands": {"ffmpeg": "ffmpeg", "ffprobe": "ffprobe"},
    },
    "pdf-render": {
        "modules": {},
        "commands": {"pdftoppm": "pdftoppm"},
    },
    # One lane per markdown deck tool rather than one `markdown-deck` lane over
    # all four. A lane is an AND over its commands, and no vault authors decks
    # in every tool at once: a single lane would report a presenterm-only vault
    # as degraded for the three renderers it will never call. Each degrades on
    # its own, and `render-markdown-deck.py` requires exactly the one the deck's
    # detected flavor names.
    "markdown-deck-presenterm": {
        "modules": {},
        # presenterm shells out to weasyprint for the PDF itself.
        "commands": {"presenterm": "presenterm", "weasyprint": "weasyprint"},
    },
    "markdown-deck-slidev": {
        "modules": {},
        "commands": {"slidev": "slidev"},
    },
    "markdown-deck-marp": {
        "modules": {},
        "commands": {"marp": "marp"},
    },
    "markdown-deck-reveal-md": {
        "modules": {},
        "commands": {"reveal-md": "reveal-md"},
    },
}
DEFAULT_LANES = ("core", "pdf", "pptx")
DEFAULT_REQUIRED_LANES = ("core",)


class ModuleProbeResult(TypedDict):
    """Parent-side result for one isolated dependency import."""

    available: bool
    failure: dict[str, object] | None


class CommandProbeResult(TypedDict):
    """Result for one executable dependency probe."""

    available: bool
    failure: dict[str, object] | None


def _failed_module_probe(reason: str, **details: object) -> ModuleProbeResult:
    failure: dict[str, object] = {"reason": reason}
    failure.update(details)
    return {"available": False, "failure": failure}


# The child's exit status is the whole protocol. Python itself exits 1 on an
# uncaught exception, so a dependency whose initializer raises reads as 1; a
# missing module is caught and reported as 3 instead.
_IMPORT_PROBE_SOURCE = (
    "import importlib, sys\n"
    "try:\n"
    "    importlib.import_module(sys.argv[1])\n"
    "except ImportError:\n"
    "    sys.exit(3)\n"
)
_INITIALIZER_EXCEPTION_EXIT = 1
_UNAVAILABLE_IMPORT_EXIT = 3


def _signal_name(signal_number: int) -> str:
    try:
        return signal.Signals(signal_number).name
    except ValueError:
        return f"SIG{signal_number}"


def _probe_module(
    import_name: str,
    *,
    runner: Callable[..., subprocess.CompletedProcess[object]] | None = None,
) -> ModuleProbeResult:
    """Import one module in a bounded child of this exact interpreter.

    A child rather than an in-process import, because a native extension can
    crash the interpreter and a cold network filesystem can stall an import for
    minutes; either must stay local to its lane.
    """
    run = subprocess.run if runner is None else runner
    try:
        completed = run(
            [sys.executable, "-c", _IMPORT_PROBE_SOURCE, import_name],
            # `-c` puts the working directory on sys.path; pin it so a stray
            # module in the caller's directory cannot shadow the dependency.
            cwd=str(Path(__file__).resolve().parent),
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            check=False,
            timeout=MODULE_PROBE_TIMEOUT_SECONDS,
        )
    except subprocess.TimeoutExpired:
        return _failed_module_probe(
            "timeout",
            timeout_seconds=MODULE_PROBE_TIMEOUT_SECONDS,
        )
    except OSError as exc:
        return _failed_module_probe(
            "probe_start_failure",
            exception_type=type(exc).__name__,
        )
    code = completed.returncode
    if code == 0:
        return {"available": True, "failure": None}
    if code == _UNAVAILABLE_IMPORT_EXIT:
        return _failed_module_probe("unavailable_import")
    if code == _INITIALIZER_EXCEPTION_EXIT:
        return _failed_module_probe("initializer_exception")
    if code < 0:
        return _failed_module_probe(
            "native_crash",
            termination="signal",
            signal_number=-code,
            signal_name=_signal_name(-code),
        )
    return _failed_module_probe("native_crash", termination="exit", exit_code=code)


def _command_available(command: str) -> bool:
    return shutil.which(command) is not None


def unresolved_module_probes(report: Mapping[str, Any]) -> dict[str, str]:
    """Map each module whose probe never answered to the reason it did not.

    Separated from the missing set because the two need different repairs: a
    missing module is one the probe found absent, repaired by installing it; an
    unresolved one is a module whose presence the probe never established,
    usually repaired by warming the interpreter it lives on.
    """
    unresolved: dict[str, str] = {}
    for lane in report.get("lanes", {}).values():
        failures = lane.get("module_failures", {})
        for name in lane.get("unresolved_modules", []):
            failure = failures.get(name)
            if isinstance(failure, dict):
                unresolved[name] = str(failure.get("reason"))
    return unresolved


def _unresolved_advice(report: Mapping[str, Any]) -> str:
    """Name the modules whose presence is unknown, and the repair that fits."""
    unresolved = unresolved_module_probes(report)
    if not unresolved:
        return ""
    named = ", ".join(
        f"{name} ({reason})" for name, reason in sorted(unresolved.items())
    )
    return (
        f". NOTE: the probe did not resolve {named}, so these may be installed "
        "but slow to import rather than absent — an interpreter on a network "
        "filesystem reads its dependencies over the network on a cold import. "
        "Read the package files once to warm them, then rerun this check, "
        "before reinstalling anything"
    )


def _probe_command(label: str, command: str) -> CommandProbeResult:
    """Probe presence; yt-dlp resolves through the toolkit's own order first."""
    if label != "yt-dlp":
        available = _command_available(command)
        return {
            "available": available,
            "failure": None if available else {"reason": "not_found"},
        }
    try:
        resolve_ytdlp()
    except YtDlpResolutionError as exc:
        return {"available": False, "failure": {"reason": exc.code}}
    return {"available": True, "failure": None}


def _parse_lanes(value: str) -> tuple[str, ...]:
    lanes = tuple(dict.fromkeys(part.strip() for part in value.split(",")))
    if not lanes or any(not lane for lane in lanes):
        raise argparse.ArgumentTypeError(
            "lane list must not be empty; pass a comma-separated value such as core"
        )
    unknown = sorted(set(lanes) - set(LANE_REQUIREMENTS))
    if unknown:
        raise argparse.ArgumentTypeError(
            f"unknown lanes {unknown}; choose from {sorted(LANE_REQUIREMENTS)}"
        )
    return lanes


def build_report(
    lanes: tuple[str, ...],
    required_lanes: tuple[str, ...],
) -> dict[str, Any]:
    """Return one deterministic report for the running interpreter."""
    selected = tuple(dict.fromkeys((*lanes, *required_lanes, "core")))
    required = frozenset((*required_lanes, "core"))
    python_supported = sys.version_info[:2] >= MINIMUM_PYTHON
    lane_reports: dict[str, dict[str, Any]] = {}
    for lane in selected:
        requirements = LANE_REQUIREMENTS[lane]
        module_probes = {
            distribution: _probe_module(import_name)
            for distribution, import_name in requirements["modules"].items()
        }
        modules = {
            distribution: probe["available"]
            for distribution, probe in module_probes.items()
        }
        module_failures = {
            distribution: probe["failure"]
            for distribution, probe in module_probes.items()
            if probe["failure"] is not None
        }
        command_probes = {
            label: _probe_command(label, command)
            for label, command in requirements["commands"].items()
        }
        commands = {
            label: probe["available"] for label, probe in command_probes.items()
        }
        command_failures = {
            label: probe["failure"]
            for label, probe in command_probes.items()
            if probe["failure"] is not None
        }
        missing_modules = sorted(
            name for name, available in modules.items() if not available
        )
        # A probe that never finished says nothing about whether the module is
        # installed. Reporting one as missing sends an operator to install a
        # package that is already there — the repair for a cold interpreter on a
        # network filesystem is to warm it, not to reinstall it. `missing_modules`
        # keeps every unavailable name so existing readers are unaffected; this
        # names the subset whose answer is unknown rather than "absent".
        unresolved_modules = sorted(
            name
            for name, failure in module_failures.items()
            if isinstance(failure, dict)
            and failure.get("reason") in UNRESOLVED_PROBE_REASONS
        )
        missing_commands = sorted(
            name for name, available in commands.items() if not available
        )
        available = not missing_modules and not missing_commands
        if lane == "core" and not python_supported:
            available = False
        lane_reports[lane] = {
            "available": available,
            "required": lane in required,
            "modules": modules,
            "module_failures": module_failures,
            "commands": commands,
            "command_failures": command_failures,
            "missing_modules": missing_modules,
            "unresolved_modules": unresolved_modules,
            "missing_commands": missing_commands,
        }
    blocking = sorted(lane for lane in required if not lane_reports[lane]["available"])
    degraded = sorted(
        lane
        for lane, report in lane_reports.items()
        if not report["available"] and lane not in required
    )
    return {
        "schema_version": REPORT_SCHEMA_VERSION,
        "ok": not blocking,
        "python_executable": sys.executable,
        "python_version": ".".join(str(part) for part in sys.version_info[:3]),
        "minimum_python": ".".join(str(part) for part in MINIMUM_PYTHON),
        "lanes": lane_reports,
        "blocking_lanes": blocking,
        "degraded_lanes": degraded,
    }


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=(__doc__ or "").split("\n")[0])
    parser.add_argument(
        "--lanes",
        type=_parse_lanes,
        default=DEFAULT_LANES,
        help=(
            "comma-separated lanes to inspect; choices: "
            + ",".join(sorted(LANE_REQUIREMENTS))
        ),
    )
    parser.add_argument(
        "--require-lanes",
        type=_parse_lanes,
        default=DEFAULT_REQUIRED_LANES,
        help="comma-separated lanes whose absence must produce exit 1",
    )
    args = parser.parse_args(argv)
    report = build_report(args.lanes, args.require_lanes)
    print(json.dumps(report, sort_keys=True))
    if not report["ok"]:
        blocking = ", ".join(report["blocking_lanes"])
        print(
            "vault-ingress runtime is unavailable for required lanes "
            f"{blocking}; use Python {MINIMUM_PYTHON[0]}.{MINIMUM_PYTHON[1]}+ "
            "and install the missing modules or commands, or repair failed "
            f"dependency initialization, listed in the JSON in {sys.executable}, "
            "then rerun this check" + _unresolved_advice(report),
            file=sys.stderr,
        )
    elif report["degraded_lanes"]:
        degraded = ", ".join(report["degraded_lanes"])
        print(
            "vault-ingress runtime is degraded for optional lanes "
            f"{degraded}; install the missing modules or commands, or repair "
            "failed dependency initialization, listed in the JSON in "
            f"{sys.executable}, then rerun this check" + _unresolved_advice(report),
            file=sys.stderr,
        )
    return 0 if report["ok"] else 1


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    # Callers treat a non-zero exit without report JSON as a silent precheck
    # failure; emit one failure report and recovery step because propagation
    # would suppress the machine-readable diagnostic contract.
    except Exception as exc:  # noqa: BLE001 - outer-boundary-process-contract
        print(
            json.dumps(
                {
                    "schema_version": REPORT_SCHEMA_VERSION,
                    "ok": False,
                    "python_executable": sys.executable,
                    "python_version": ".".join(
                        str(part) for part in sys.version_info[:3]
                    ),
                    "minimum_python": ".".join(str(part) for part in MINIMUM_PYTHON),
                    "lanes": {},
                    "blocking_lanes": ["runtime-probe"],
                    "degraded_lanes": [],
                    "error": f"{type(exc).__name__}: {exc}",
                },
                sort_keys=True,
            )
        )
        print(
            "vault-ingress runtime probe failed unexpectedly; repair the "
            "configured interpreter or dependency initialization named in the "
            "JSON, then rerun this check",
            file=sys.stderr,
        )
        raise SystemExit(2) from exc

skills

vault-ingress

scripts

adherence_baseline.py

aggregate-catalog-feedback.py

apply-source-repairs.py

artifact_locator.py

artifact_metadata.py

artifact_supervisor.py

audit-pattern-catalog.py

audit-persisted-pattern-observations.py

audit-source-identities.py

batch-download-videos.py

build-contact-sheet.py

build-crop-reviewer.py

build-score-basis.py

catalog_dimension_registry.py

catalog_io.py

catalog_normalization.py

catalog-pptx-deck.py

check-runtime.py

classify-pptx-evidence.py

cloud_artifacts.py

cooperative_lock.py

crop_frames.py

crop-reviewer-shell.html

crop-reviewer-shell.html.txt

crop-reviewer.js

crop-reviewer.js.txt

establish-date-provenance.py

extract-local-audio.py

failure_diagnostics.py

fetch-transcript.py

ingress_contract.py

local_media_contract.py

local_media_download.py

local_media_evidence.py

local_media_process.py

local_media_sampling.py

local_media_transcription.py

local_media_words.py

markdown_deck.py

migrate-tracking-database.py

mutate-tracking-database.py

pattern_evidence.py

pdf_evidence.py

persist-results.py

persisted_pattern_observations.py

pptx_catalog_assessment.py

pptx_catalog_selection.py

pptx_deck_facts.py

pptx_discovery_contract.py

pptx_evidence.py

pptx_talk_identity.py

pptx-extraction.py

preflight-vault.py

queue_claim_contract.py

queue-state.py

read-tracking-database.py

render-markdown-deck.py

render-vault-status.py

retained_stage.py

return_validation.py

run-obligations.py

scan-shownotes.py

shownotes_checkout.py

source_alias_contract.py

source_identity_matching.py

summary_lock.py

sweep-pptx-talk-identity.py

tracking_database_io.py

tracking_database.py

transcript_quality.py

transcript_timing.py

validate-returns.py

vault_root_authority.py

video_evidence.py

video_integrity.py

video-slide-extraction.py

vtt-cleanup.py

write-analysis.py

ytdlp_runtime.py

SKILL.md

README.md

tile.json