deepctl-cmd-debug-toolkit 0.1.0__py3-none-any.whl

deepctl_cmd_debug_toolkit/__init__.py

@@ -0,0 +1,5 @@
+"""Toolkit subcommand for dg debug — field support scripts from deepgram/support-toolkit."""
+
+from .command import ToolkitCommand
+
+__all__ = ["ToolkitCommand"]

deepctl_cmd_debug_toolkit/command.py

@@ -0,0 +1,143 @@
+"""Toolkit subcommand group — runs field support scripts from deepgram/support-toolkit."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from typing import Any
+
+import click
+from deepctl_core import AuthManager, BaseGroupCommand, Config
+from rich.console import Console
+
+from .fetcher import get_cached_manifest, get_or_fetch_script, refresh_manifest
+from .models import ToolkitScript
+
+console = Console()
+
+
+class ToolkitCommand(BaseGroupCommand):
+    """Runs field engineering scripts from deepgram/support-toolkit."""
+
+    name = "toolkit"
+    help = (
+        "Run field engineering diagnostic scripts fetched from "
+        "deepgram/support-toolkit. Scripts are downloaded on first use, "
+        "verified against their GitHub blob SHA, and cached locally."
+    )
+    short_help = "Field support scripts (deepgram/support-toolkit)"
+
+    requires_auth = False
+    requires_project = False
+    ci_friendly = True
+    invoke_without_command = False
+
+    examples = [
+        "dg debug toolkit refresh",
+        "dg debug toolkit latency wss://api.deepgram.com/v1/listen",
+        "dg debug toolkit latency wss://api.deepgram.com/v1/listen --duration=60",
+    ]
+
+    def setup_commands(self) -> list[click.Command]:
+        """Return commands derived from the cached manifest.
+
+        Intentionally never performs network I/O — reads disk cache only so
+        that every `dg` invocation stays fast. Users run `refresh` once to
+        populate the cache; individual script commands fetch lazily at invoke
+        time.
+        """
+        commands: list[click.Command] = [_make_refresh_command()]
+
+        manifest = get_cached_manifest()
+        if manifest:
+            for name, entry in manifest.commands.items():
+                commands.append(_make_script_command(name, entry))
+
+        return commands
+
+    def handle_group(
+        self,
+        config: Config,
+        auth_manager: AuthManager,
+        client: Any,
+        **kwargs: Any,
+    ) -> None:
+        # BaseGroupCommand.handle() calls handle_group() even when a subcommand
+        # is being invoked — guard here so we don't add noise to subcommand runs.
+        if click.get_current_context().invoked_subcommand is not None:
+            return
+
+        manifest = get_cached_manifest()
+        if not manifest:
+            console.print(
+                "[yellow]No toolkit scripts cached yet.[/yellow]\n"
+                "Run [bold]dg debug toolkit refresh[/bold] to fetch the "
+                "latest scripts from deepgram/support-toolkit."
+            )
+            return
+
+        console.print("[bold]Available toolkit scripts:[/bold]\n")
+        for name, entry in manifest.commands.items():
+            console.print(f"  [bold]dg debug toolkit {name}[/bold]")
+            console.print(f"  [dim]{entry.description}[/dim]\n")
+
+
+def _make_refresh_command() -> click.Command:
+    """Static 'refresh' command — always available regardless of cache state."""
+
+    @click.command(
+        "refresh", help="Fetch the latest script list from deepgram/support-toolkit."
+    )
+    def _refresh() -> None:
+        try:
+            manifest = refresh_manifest(console)
+        except Exception as exc:
+            console.print(f"[red]Error fetching manifest:[/red] {exc}")
+            sys.exit(1)
+
+        console.print(
+            f"\n[green]✓[/green] Toolkit manifest updated "
+            f"({len(manifest.commands)} script(s) available):\n"
+        )
+        for name, entry in manifest.commands.items():
+            console.print(f"  [bold]dg debug toolkit {name}[/bold]")
+            console.print(f"  [dim]{entry.description}[/dim]\n")
+
+    return _refresh
+
+
+def _make_script_command(name: str, entry: ToolkitScript) -> click.Command:
+    """Create a Click command that fetches, verifies, and runs a toolkit script."""
+
+    @click.command(
+        name,
+        help=entry.description,
+        # Forward all unrecognised args directly to the underlying script.
+        context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+    )
+    @click.argument("script_args", nargs=-1, type=click.UNPROCESSED)
+    def _run(script_args: tuple[str, ...]) -> None:
+        try:
+            script_path = get_or_fetch_script(entry, console)
+        except Exception as exc:
+            console.print(f"[red]Error fetching script:[/red] {exc}")
+            sys.exit(1)
+
+        env = os.environ.copy()
+
+        if entry.pass_api_key:
+            try:
+                api_key = AuthManager(Config()).get_api_key()
+                if api_key:
+                    env["DEEPGRAM_API_KEY"] = api_key
+            except Exception:
+                pass  # Script will surface its own missing-key error
+
+        result = subprocess.run(
+            [sys.executable, str(script_path)] + list(script_args),
+            env=env,
+        )
+        sys.exit(result.returncode)
+
+    return _run

deepctl_cmd_debug_toolkit/fetcher.py

@@ -0,0 +1,145 @@
+"""GitHub fetch, blob-SHA integrity verification, and local cache management."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import httpx
+import platformdirs
+from rich.console import Console
+
+from .models import ToolkitManifest, ToolkitScript
+
+if TYPE_CHECKING:
+    pass
+
+GITHUB_REPO = "deepgram/support-toolkit"
+GITHUB_API_BASE = f"https://api.github.com/repos/{GITHUB_REPO}/contents"
+
+_CACHE_DIR = Path(platformdirs.user_cache_dir("deepctl")) / "toolkit"
+_MANIFEST_CACHE = _CACHE_DIR / "manifest.json"
+_MANIFEST_AGE = _CACHE_DIR / "manifest.age"
+_SCRIPTS_CACHE = _CACHE_DIR / "scripts"
+_MANIFEST_TTL = 86400  # 24 hours
+
+
+def git_blob_sha(content: bytes) -> str:
+    """Compute the git blob SHA1 for integrity verification.
+
+    GitHub's Contents API returns this hash alongside file content.
+    Re-deriving it from the downloaded bytes lets us confirm we received
+    exactly what GitHub has, using their own object model as a trust anchor.
+    """
+    header = f"blob {len(content)}\0".encode()
+    return hashlib.sha1(header + content).hexdigest()
+
+
+def local_toolkit_path() -> Path | None:
+    """Return a local override path if DEEPGRAM_TOOLKIT_PATH is set."""
+    p = os.getenv("DEEPGRAM_TOOLKIT_PATH")
+    return Path(p) if p else None
+
+
+def _fetch_github_contents(path: str) -> tuple[str, bytes]:
+    """Fetch a file from the GitHub Contents API.
+
+    Returns (blob_sha, raw_bytes). Raises on any HTTP error or SHA mismatch.
+    """
+    url = f"{GITHUB_API_BASE}/{path}"
+    resp = httpx.get(
+        url,
+        headers={"Accept": "application/vnd.github+json"},
+        timeout=30.0,
+        follow_redirects=True,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    sha: str = data["sha"]
+    content = base64.b64decode(data["content"])
+
+    # Verify the download is exactly what GitHub reported.
+    if git_blob_sha(content) != sha:
+        raise RuntimeError(
+            f"Integrity check failed for {path}: "
+            f"downloaded content does not match GitHub blob SHA."
+        )
+    return sha, content
+
+
+def get_cached_manifest() -> ToolkitManifest | None:
+    """Return the cached manifest if it exists and is fresh, else None."""
+    if not _MANIFEST_CACHE.exists():
+        return None
+    if _MANIFEST_AGE.exists():
+        try:
+            age = float(_MANIFEST_AGE.read_text().strip())
+            if time.time() - age > _MANIFEST_TTL:
+                return None  # Stale — caller should refresh
+        except Exception:
+            return None
+    try:
+        return ToolkitManifest.model_validate_json(_MANIFEST_CACHE.read_text())
+    except Exception:
+        return None
+
+
+def refresh_manifest(console: Console) -> ToolkitManifest:
+    """Fetch the toolkit manifest, verify it, cache it, and return it."""
+    local = local_toolkit_path()
+    if local:
+        manifest_file = local / "toolkit.json"
+        content = manifest_file.read_bytes()
+        console.print(f"[dim]Loading toolkit manifest from {local}[/dim]")
+    else:
+        console.print(
+            f"[dim]Fetching toolkit manifest from github.com/{GITHUB_REPO}...[/dim]"
+        )
+        _sha, content = _fetch_github_contents("toolkit.json")
+
+    manifest = ToolkitManifest.model_validate_json(content)
+
+    _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    _MANIFEST_CACHE.write_bytes(content)
+    _MANIFEST_AGE.write_text(str(time.time()))
+
+    return manifest
+
+
+def get_or_fetch_script(entry: ToolkitScript, console: Console) -> Path:
+    """Return the path to a verified local copy of the script.
+
+    Uses a local override if DEEPGRAM_TOOLKIT_PATH is set, otherwise
+    fetches from GitHub and caches by blob SHA. Re-downloads only when the
+    cached SHA no longer matches the stored value.
+    """
+    local = local_toolkit_path()
+    if local:
+        return local / entry.script
+
+    # Stable cache filename derived from the script path.
+    safe_name = entry.script.replace("/", "__")
+    cache_file = _SCRIPTS_CACHE / safe_name
+    sha_file = _SCRIPTS_CACHE / f"{safe_name}.sha"
+
+    # Use cache if content still matches its stored SHA.
+    if cache_file.exists() and sha_file.exists():
+        stored_sha = sha_file.read_text().strip()
+        if git_blob_sha(cache_file.read_bytes()) == stored_sha:
+            return cache_file
+
+    # Download from GitHub with integrity verification.
+    script_name = Path(entry.script).name
+    console.print(f"[blue]Downloading[/blue] {script_name} from support-toolkit...")
+    sha, content = _fetch_github_contents(entry.script)
+
+    _SCRIPTS_CACHE.mkdir(parents=True, exist_ok=True)
+    cache_file.write_bytes(content)
+    sha_file.write_text(sha)
+
+    console.print(f"[green]✓[/green] {script_name} verified (sha: {sha[:12]}…)")
+    return cache_file

deepctl_cmd_debug_toolkit/models.py

@@ -0,0 +1,20 @@
+"""Models for the toolkit manifest."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class ToolkitScript(BaseModel):
+    """A single script entry from toolkit.json."""
+
+    description: str
+    script: str  # Relative path within the support-toolkit repo
+    pass_api_key: bool = False  # Inject DEEPGRAM_API_KEY into subprocess env
+
+
+class ToolkitManifest(BaseModel):
+    """Parsed representation of toolkit.json."""
+
+    version: str
+    commands: dict[str, ToolkitScript]

deepctl_cmd_debug_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: deepctl-cmd-debug-toolkit
+Version: 0.1.0
+Summary: Toolkit subcommand for dg debug — runs field support scripts from deepgram/support-toolkit
+Author-email: Deepgram <devrel@deepgram.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: deepctl-core>=0.1.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.10.1
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: rich>=13.9.4
+Requires-Dist: click>=8.1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.3; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: mypy>=1.13.0; extra == "dev"
+Requires-Dist: ruff>=0.8.1; extra == "dev"
+
+# deepctl-cmd-debug-toolkit
+
+> Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
+
+Toolkit subcommand for dg debug — runs field support scripts from deepgram/support-toolkit
+
+This is a subcommand of `deepctl debug`.
+
+## Installation
+
+This package is included with deepctl and does not need to be installed separately.
+
+### Install deepctl
+
+```bash
+# Install with pip
+pip install deepctl
+
+# Or install with uv
+uv tool install deepctl
+
+# Or install with pipx
+pipx install deepctl
+
+# Or run without installing
+uvx deepctl --help
+pipx run deepctl --help
+```
+
+## Commands
+
+| Command | Entry Point |
+|---------|-------------|
+| `deepctl debug toolkit` | `deepctl_cmd_debug_toolkit.command:ToolkitCommand` |
+
+## Dependencies
+
+- `httpx>=0.27.0`
+- `pydantic>=2.10.1`
+- `platformdirs>=4.0.0`
+- `rich>=13.9.4`
+- `click>=8.1.7`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

deepctl_cmd_debug_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+deepctl_cmd_debug_toolkit/__init__.py,sha256=koXSDCTIRP3qm6Aa__0bGkrfMGP0QQK53EEwk5VbKcI,162
+deepctl_cmd_debug_toolkit/command.py,sha256=kXK386bSHtWcHsn_c8C3Lwql5ycSGC8VRttAEemXHgw,4909
+deepctl_cmd_debug_toolkit/fetcher.py,sha256=xeeefB8Ev672k0VCEEVFC_89soP_1gk5jvnY1Lu3AOQ,4832
+deepctl_cmd_debug_toolkit/models.py,sha256=boToXfTJWbRXmZdbmwhSByul3V8TySUGTaSlp-IkAjI,499
+deepctl_cmd_debug_toolkit-0.1.0.dist-info/METADATA,sha256=KUbeEu83nRjHWM-wBo3ZlngNRnPJeTrOT51O5lI-84Y,1590
+deepctl_cmd_debug_toolkit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+deepctl_cmd_debug_toolkit-0.1.0.dist-info/entry_points.txt,sha256=L1Lk43utOWOLoEMRdwWC7OX0re75omA4y9ZIwAvJyw8,87
+deepctl_cmd_debug_toolkit-0.1.0.dist-info/top_level.txt,sha256=nY0EOsmsW2gdj-lQZNzh8bhkrGXZMvnNpLLy6FJJpfQ,26
+deepctl_cmd_debug_toolkit-0.1.0.dist-info/RECORD,,

deepctl_cmd_debug_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deepctl_cmd_debug_toolkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[deepctl.subcommands.debug]
+toolkit = deepctl_cmd_debug_toolkit.command:ToolkitCommand

deepctl_cmd_debug_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+deepctl_cmd_debug_toolkit