deepctl-cmd-init 0.0.2__py3-none-any.whl

deepctl_cmd_init/__init__.py

@@ -0,0 +1,6 @@
+"""Init command package for deepctl."""
+
+from .command import InitCommand
+from .models import InitResult
+
+__all__ = ["InitCommand", "InitResult"]

deepctl_cmd_init/command.py

@@ -0,0 +1,321 @@
+"""Init command for deepctl — scaffold Deepgram starter apps."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import click
+from deepctl_core import (
+    AuthManager,
+    BaseCommand,
+    Config,
+    DeepgramClient,
+)
+from rich.console import Console
+from rich.table import Table
+
+from . import lifecycle, templates_api
+from .models import InitResult, TemplateDetail, TemplateInfo
+
+console = Console()
+
+
+class InitCommand(BaseCommand):
+    """Scaffold a Deepgram starter app from the templates gallery."""
+
+    name = "init"
+    help = (
+        "Browse, clone, and set up Deepgram starter apps. "
+        "Fetches templates from the Deepgram templates gallery and "
+        "optionally runs install/start lifecycle steps."
+    )
+    short_help = "Scaffold a Deepgram starter app"
+
+    requires_auth = False
+    requires_project = False
+    ci_friendly = True
+
+    examples = [
+        "dg init",
+        "dg init --search python",
+        "dg init node-transcription",
+        "dg init node-transcription --dir ./my-app",
+        "dg init node-transcription --install --start",
+        "dg init --list",
+        "dg init --list --search flask",
+    ]
+    agent_help = (
+        "Scaffold a Deepgram starter app from the templates gallery. "
+        "Can list available templates, search/filter them, or clone a "
+        "specific template by name. After cloning, optionally runs "
+        "install and start lifecycle steps defined in deepgram.toml. "
+        "If authenticated, injects DEEPGRAM_API_KEY into .env automatically."
+    )
+
+    def get_arguments(self) -> list[dict[str, Any]]:
+        """Get command arguments and options."""
+        return [
+            {
+                "name": "template",
+                "help": "Template name/slug to clone directly",
+                "type": str,
+                "required": False,
+                "default": None,
+            },
+            {
+                "names": ["--dir", "-d"],
+                "help": "Target directory (default: ./{template-name})",
+                "type": str,
+                "is_option": True,
+            },
+            {
+                "names": ["--search", "-s"],
+                "help": "Filter templates by search term",
+                "type": str,
+                "is_option": True,
+            },
+            {
+                "names": ["--list", "-l"],
+                "help": "List matching templates and exit",
+                "is_flag": True,
+                "is_option": True,
+            },
+            {
+                "names": ["--install"],
+                "help": "Run install step without prompting",
+                "is_flag": True,
+                "is_option": True,
+            },
+            {
+                "names": ["--start"],
+                "help": "Run start step without prompting",
+                "is_flag": True,
+                "is_option": True,
+            },
+            {
+                "names": ["--no-install"],
+                "help": "Skip install step without prompting",
+                "is_flag": True,
+                "is_option": True,
+            },
+            {
+                "names": ["--no-start"],
+                "help": "Skip start step without prompting",
+                "is_flag": True,
+                "is_option": True,
+            },
+        ]
+
+    def handle(
+        self,
+        config: Config,
+        auth_manager: AuthManager,
+        client: DeepgramClient,
+        **kwargs: Any,
+    ) -> Any:
+        """Handle the init command."""
+        template_slug: str | None = kwargs.get("template")
+        target_dir: str | None = kwargs.get("dir")
+        search: str | None = kwargs.get("search")
+        list_mode: bool = kwargs.get("list", False)
+        do_install: bool = kwargs.get("install", False)
+        do_start: bool = kwargs.get("start", False)
+        no_install: bool = kwargs.get("no_install", False)
+        no_start: bool = kwargs.get("no_start", False)
+
+        # --- List mode ---
+        if list_mode:
+            return self._handle_list(search)
+
+        # --- Direct template selection ---
+        if template_slug:
+            detail = self._fetch_template(template_slug)
+            if not detail:
+                return InitResult(
+                    status="error", message=f"Template not found: {template_slug}"
+                )
+        else:
+            # --- Interactive picker ---
+            detail = self._interactive_pick(search)
+            if not detail:
+                return InitResult(status="cancelled", message="No template selected")
+
+        # Resolve target directory
+        dest = Path(target_dir) if target_dir else Path(f"./{detail.name}")
+        dest = dest.resolve()
+
+        # Confirm selection
+        self._print_template_summary(detail)
+        console.print(f"[dim]Directory:[/dim] {dest}")
+        console.print()
+
+        if not self.confirm("Clone this template?", default=True):
+            return InitResult(status="cancelled", message="Clone cancelled")
+
+        # Clone
+        github_url = detail.links.get("github")
+        if not github_url:
+            return InitResult(status="error", message="Template has no GitHub URL")
+
+        console.print()
+        with console.status("[blue]Cloning template...[/blue]"):
+            lifecycle.clone_template(github_url, dest)
+        console.print(f"[green]Cloned to {dest}[/green]")
+
+        # Inject API key if authenticated
+        try:
+            api_key = auth_manager.get_api_key()
+            if api_key:
+                lifecycle.inject_env(dest, api_key)
+        except Exception:
+            pass  # Auth is optional
+
+        installed = False
+        started = False
+
+        # Run lifecycle steps if config exists
+        if detail.config:
+            # Install step
+            if detail.config.install:
+                should_install = do_install or (
+                    not no_install and self.confirm("Run install step?", default=True)
+                )
+                if should_install:
+                    console.print()
+                    installed = lifecycle.run_lifecycle_step(
+                        detail.config.install, dest
+                    )
+
+            # Start step
+            if detail.config.start:
+                should_start = do_start or (
+                    not no_start and self.confirm("Run start step?", default=True)
+                )
+                if should_start:
+                    console.print()
+                    started = lifecycle.run_lifecycle_step(detail.config.start, dest)
+
+        # Summary
+        console.print()
+        console.print(
+            f"[green bold]Done![/green bold] Your app is ready at [cyan]{dest}[/cyan]"
+        )
+        if not installed and detail.config and detail.config.install:
+            console.print(
+                f"[dim]To install: cd {dest.name} && run the install command[/dim]"
+            )
+        if not started and detail.config and detail.config.start:
+            console.print(
+                f"[dim]To start: cd {dest.name} && run the start command[/dim]"
+            )
+
+        return InitResult(
+            status="success",
+            message=f"Cloned {detail.name}",
+            template=detail.name,
+            directory=str(dest),
+            installed=installed,
+            started=started,
+        )
+
+    def output_result(self, result: Any, config: Config) -> None:
+        """Only emit structured output when an explicit --output format is set."""
+        from deepctl_core.output import get_output_format
+
+        output_format = get_output_format()
+
+        # Default format: the Rich table / console messages are already printed,
+        # so skip the automatic JSON dump.
+        if output_format in ("default",):
+            return
+
+        # Explicit --output json/yaml/table/csv: delegate to base
+        super().output_result(result, config)
+
+    def _handle_list(self, search: str | None) -> list[dict[str, Any]]:
+        """List templates and return structured data."""
+        with console.status("[blue]Fetching templates...[/blue]"):
+            response = templates_api.list_templates(search=search)
+
+        templates = response.items
+        if not templates:
+            console.print("[yellow]No templates found[/yellow]")
+            return []
+
+        self._print_templates_table(templates)
+        console.print(f"\n[dim]{len(templates)} template(s) found[/dim]")
+
+        return [t.model_dump() for t in templates]
+
+    def _interactive_pick(self, search: str | None) -> TemplateDetail | None:
+        """Show interactive picker and return selected template detail."""
+        with console.status("[blue]Fetching templates...[/blue]"):
+            response = templates_api.list_templates(search=search)
+
+        templates = response.items
+        if not templates:
+            console.print("[yellow]No templates found[/yellow]")
+            return None
+
+        self._print_templates_table(templates)
+        console.print()
+
+        try:
+            choice = click.prompt(
+                "Select a template",
+                type=click.IntRange(1, len(templates)),
+            )
+        except (click.Abort, EOFError):
+            return None
+
+        selected = templates[choice - 1]
+        console.print()
+
+        # Fetch full detail
+        with console.status(f"[blue]Fetching {selected.name}...[/blue]"):
+            return templates_api.get_template(selected.name)
+
+    def _fetch_template(self, slug: str) -> TemplateDetail | None:
+        """Fetch template detail by slug, handling errors."""
+        try:
+            with console.status(f"[blue]Fetching {slug}...[/blue]"):
+                return templates_api.get_template(slug)
+        except Exception as e:
+            console.print(f"[red]Error:[/red] {e}")
+            return None
+
+    def _print_templates_table(self, templates: list[TemplateInfo]) -> None:
+        """Print a numbered table of templates."""
+        table = Table(show_header=True, header_style="bold blue")
+        table.add_column("#", style="dim", width=4, justify="right")
+        table.add_column("Name")
+        table.add_column("Language")
+        table.add_column("Framework")
+        table.add_column("Category")
+
+        for i, t in enumerate(templates, 1):
+            table.add_row(
+                str(i),
+                t.name,
+                t.language,
+                t.framework or "—",
+                t.category or "—",
+            )
+
+        console.print(table)
+
+    def _print_template_summary(self, detail: TemplateDetail) -> None:
+        """Print a summary of the selected template."""
+        console.print()
+        console.print(f"[bold]{detail.title}[/bold]")
+        console.print(f"[dim]{detail.description}[/dim]")
+        console.print(
+            f"Language: [cyan]{detail.language}[/cyan]"
+            + (
+                f"  Framework: [cyan]{detail.framework}[/cyan]"
+                if detail.framework
+                else ""
+            )
+            + (f"  Stars: {detail.stats.stars}" if detail.stats.stars else "")
+        )

deepctl_cmd_init/lifecycle.py

@@ -0,0 +1,104 @@
+"""Clone template repos and run lifecycle steps from deepgram.toml."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from .models import LifecycleStep
+
+console = Console()
+
+
+def clone_template(github_url: str, target_dir: Path) -> None:
+    """Clone a template repo with depth 1, then remove .git.
+
+    Args:
+        github_url: Full GitHub URL to clone.
+        target_dir: Local directory to clone into.
+
+    Raises:
+        RuntimeError: If git clone fails.
+    """
+    if target_dir.exists():
+        raise RuntimeError(f"Directory already exists: {target_dir}")
+
+    result = subprocess.run(
+        ["git", "clone", "--depth", "1", github_url, str(target_dir)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"git clone failed: {result.stderr.strip()}")
+
+    # Remove .git so the user starts fresh
+    git_dir = target_dir / ".git"
+    if git_dir.exists():
+        shutil.rmtree(git_dir)
+
+
+def inject_env(target_dir: Path, api_key: str) -> None:
+    """Create or append DEEPGRAM_API_KEY to .env in target_dir.
+
+    Args:
+        target_dir: Directory containing the cloned template.
+        api_key: Deepgram API key to inject.
+    """
+    env_path = target_dir / ".env"
+
+    # Check if key already present
+    if env_path.exists():
+        content = env_path.read_text()
+        if "DEEPGRAM_API_KEY=" in content:
+            console.print("[dim]DEEPGRAM_API_KEY already set in .env, skipping[/dim]")
+            return
+        # Append with newline separator
+        with open(env_path, "a") as f:
+            if not content.endswith("\n"):
+                f.write("\n")
+            f.write(f"DEEPGRAM_API_KEY={api_key}\n")
+    else:
+        env_path.write_text(f"DEEPGRAM_API_KEY={api_key}\n")
+
+    console.print("[green]Injected DEEPGRAM_API_KEY into .env[/green]")
+
+
+def run_lifecycle_step(step: LifecycleStep, cwd: Path) -> bool:
+    """Execute a lifecycle step from deepgram.toml.
+
+    Args:
+        step: The lifecycle step definition.
+        cwd: Working directory for command execution.
+
+    Returns:
+        True if the step succeeded, False otherwise.
+    """
+    if step.command is None:
+        return True
+
+    commands = step.command if isinstance(step.command, list) else [step.command]
+
+    for cmd in commands:
+        if step.message:
+            console.print(f"[blue]{step.message}[/blue]")
+        else:
+            console.print(f"[dim]Running: {cmd}[/dim]")
+
+        result = subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            shell=True,
+        )
+        if result.returncode != 0:
+            console.print(
+                f"[red]Command failed (exit {result.returncode}):[/red] {cmd}"
+            )
+            return False
+
+    return True

deepctl_cmd_init/models.py

@@ -0,0 +1,79 @@
+"""Models for init command."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from deepctl_core import BaseResult
+from pydantic import BaseModel, Field
+
+
+class TemplateInfo(BaseModel):
+    """Summary info for a template (from list endpoint)."""
+
+    name: str
+    title: str
+    description: str
+    language: str
+    framework: str | None = None
+    category: str | None = None
+
+
+class TemplateStats(BaseModel):
+    """Repository statistics for a template."""
+
+    stars: int = 0
+    forks: int = 0
+    last_updated: str | None = Field(default=None, alias="lastUpdated")
+
+    model_config = {"populate_by_name": True}
+
+
+class LifecycleStep(BaseModel):
+    """A single lifecycle step from deepgram.toml."""
+
+    command: str | list[str] | None = None
+    message: str | None = None
+    parallel: bool | None = None
+    pre: dict[str, Any] | None = None
+    post: dict[str, Any] | None = None
+
+
+class TomlConfig(BaseModel):
+    """Parsed deepgram.toml configuration."""
+
+    check: LifecycleStep | None = None
+    install: LifecycleStep | None = None
+    start: LifecycleStep | None = None
+
+
+class TemplateDetail(TemplateInfo):
+    """Full template detail (from detail endpoint)."""
+
+    sdk: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    links: dict[str, str | None] = Field(default_factory=dict)
+    stats: TemplateStats = Field(default_factory=TemplateStats)
+    readme: str | None = None
+    config: TomlConfig | None = None
+
+
+class TemplateListResponse(BaseModel):
+    """Response from the templates list API."""
+
+    total: int = 0
+    page: int = 1
+    limit: int = 100
+    total_pages: int = Field(default=1, alias="totalPages")
+    items: list[TemplateInfo] = Field(default_factory=list)
+
+    model_config = {"populate_by_name": True}
+
+
+class InitResult(BaseResult):
+    """Result from init command."""
+
+    template: str | None = None
+    directory: str | None = None
+    installed: bool = False
+    started: bool = False

deepctl_cmd_init/templates_api.py

@@ -0,0 +1,80 @@
+"""HTTP client for the Deepgram templates API."""
+
+from __future__ import annotations
+
+import httpx
+
+from .models import TemplateDetail, TemplateInfo, TemplateListResponse
+
+BASE_URL = "https://templates.dx.deepgram.com"
+DEFAULT_TIMEOUT = 15.0
+
+
+def list_templates(
+    search: str | None = None,
+    page: int = 1,
+    limit: int = 100,
+) -> TemplateListResponse:
+    """Fetch templates from the API.
+
+    Args:
+        search: Optional search/filter term.
+        page: Page number (1-based).
+        limit: Results per page.
+
+    Returns:
+        Parsed template list response.
+    """
+    params: dict[str, str | int] = {"page": page, "limit": limit}
+    if search:
+        params["search"] = search
+
+    resp = httpx.get(
+        f"{BASE_URL}/api/templates",
+        params=params,
+        timeout=DEFAULT_TIMEOUT,
+    )
+    resp.raise_for_status()
+    return TemplateListResponse.model_validate(resp.json())
+
+
+def get_template(slug: str) -> TemplateDetail:
+    """Fetch a single template by slug.
+
+    Args:
+        slug: Template name/slug (e.g. "node-transcription").
+
+    Returns:
+        Parsed template detail.
+    """
+    resp = httpx.get(
+        f"{BASE_URL}/api/templates/{slug}",
+        timeout=DEFAULT_TIMEOUT,
+    )
+    resp.raise_for_status()
+    return TemplateDetail.model_validate(resp.json())
+
+
+def filter_templates(templates: list[TemplateInfo], search: str) -> list[TemplateInfo]:
+    """Client-side filter of templates by search term.
+
+    Matches against name, title, description, language, framework, and category.
+
+    Args:
+        templates: List of templates to filter.
+        search: Search term (case-insensitive).
+
+    Returns:
+        Filtered list.
+    """
+    term = search.lower()
+    results: list[TemplateInfo] = []
+    for t in templates:
+        fields = [t.name, t.title, t.description, t.language]
+        if t.framework:
+            fields.append(t.framework)
+        if t.category:
+            fields.append(t.category)
+        if any(term in f.lower() for f in fields):
+            results.append(t)
+    return results

deepctl_cmd_init-0.0.2.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: deepctl-cmd-init
+Version: 0.0.2
+Summary: Init command for deepctl — scaffold Deepgram starter apps
+Author-email: Deepgram <devrel@deepgram.com>
+Maintainer-email: Deepgram <devrel@deepgram.com>
+License-Expression: MIT
+Keywords: deepgram,cli,init,starter,templates
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: deepctl-core>=0.1.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+
+# deepctl-cmd-init
+
+> Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
+
+Init command for deepctl — scaffold Deepgram starter apps
+
+## 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 init` | `deepctl_cmd_init.command:InitCommand` |
+
+## Dependencies
+
+- `click>=8.0.0`
+- `rich>=13.0.0`
+- `httpx>=0.24.0`
+- `pydantic>=2.0.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

deepctl_cmd_init-0.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+deepctl_cmd_init/__init__.py,sha256=mJ3X78F-lDDsIxAdV8I8O_cG0w--U641JCzrLZ-pftA,146
+deepctl_cmd_init/command.py,sha256=IP_QZJ0aEQFMhPA_ySDbCvbz08a-W2IxUC0wVJY1kbc,11079
+deepctl_cmd_init/lifecycle.py,sha256=5-ICKF3RTI-erUoJmMBHKKfF-8onSXXsrsBZLdTpMV0,2907
+deepctl_cmd_init/models.py,sha256=uhBYvCYrOSbZ-mdrEwbCorApB89RemIAUtvBbNlxO4A,1971
+deepctl_cmd_init/templates_api.py,sha256=0BDO8lFlmAEcaro1rDf213T2qv01d22zaL6cy0KCdVg,2068
+deepctl_cmd_init-0.0.2.dist-info/METADATA,sha256=EhFy6qYfHtXc6P9Hgaw0e5KXZPLI0Ap59EHoHDYofuA,1563
+deepctl_cmd_init-0.0.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+deepctl_cmd_init-0.0.2.dist-info/entry_points.txt,sha256=lAaUfHpN1Zj3TwaOqgFfCu-WcK9BJgDkt0jD9v1nCq0,63
+deepctl_cmd_init-0.0.2.dist-info/top_level.txt,sha256=2eTFp6AsUibDM5tRczLTEtdiznBPlMg1I14QCR38qoM,17
+deepctl_cmd_init-0.0.2.dist-info/RECORD,,

deepctl_cmd_init-0.0.2.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_init-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[deepctl.commands]
+init = deepctl_cmd_init.command:InitCommand

deepctl_cmd_init-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+deepctl_cmd_init