dhub-cli 0.1.0__py3-none-any.whl

dhub/cli/runtime.py

@@ -0,0 +1,87 @@
+"""CLI command for running skills locally."""
+
+import subprocess
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def run_command(
+    skill_ref: str = typer.Argument(help="Skill reference: org/skill"),
+    extra_args: list[str] = typer.Argument(None, help="Extra arguments to pass to the skill"),
+) -> None:
+    """Run a locally installed skill using its configured runtime."""
+    from dhub.core.install import get_dhub_skill_path
+    from dhub.core.runtime import (
+        build_env_vars,
+        build_uv_run_command,
+        build_uv_sync_command,
+        validate_local_runtime_prerequisites,
+    )
+    from dhub.core.manifest import parse_skill_md
+
+    # Parse org/skill reference
+    parts = skill_ref.split("/", 1)
+    if len(parts) != 2:
+        console.print(
+            "[red]Error: Skill reference must be in org/skill format.[/]"
+        )
+        raise typer.Exit(1)
+    org_slug, skill_name = parts
+
+    # Resolve the local skill directory
+    skill_dir = get_dhub_skill_path(org_slug, skill_name)
+    if not skill_dir.exists():
+        console.print(
+            f"[red]Error: Skill '{skill_ref}' is not installed. "
+            f"Expected at {skill_dir}[/]"
+        )
+        raise typer.Exit(1)
+
+    # Parse SKILL.md to get runtime config
+    skill_md_path = skill_dir / "SKILL.md"
+    if not skill_md_path.exists():
+        console.print(
+            f"[red]Error: SKILL.md not found in {skill_dir}[/]"
+        )
+        raise typer.Exit(1)
+
+    manifest = parse_skill_md(skill_md_path)
+
+    if manifest.runtime is None:
+        console.print(
+            "[red]Error: This skill has no runtime configuration.[/]"
+        )
+        raise typer.Exit(1)
+
+    if manifest.runtime.driver != "local/uv":
+        console.print(
+            f"[red]Error: Unsupported runtime driver '{manifest.runtime.driver}'. "
+            f"Only 'local/uv' is supported.[/]"
+        )
+        raise typer.Exit(1)
+
+    # Validate prerequisites
+    errors = validate_local_runtime_prerequisites(skill_dir, manifest.runtime)
+    if errors:
+        console.print("[red]Runtime prerequisites not met:[/]")
+        for error in errors:
+            console.print(f"  [red]- {error}[/]")
+        raise typer.Exit(1)
+
+    # Build environment variables
+    env = build_env_vars(manifest.runtime)
+
+    # Sync dependencies
+    sync_cmd = build_uv_sync_command(skill_dir)
+    console.print(f"[dim]Syncing dependencies in {skill_dir}...[/]")
+    subprocess.run(sync_cmd, check=True, env=env)
+
+    # Run the entrypoint
+    args_tuple = tuple(extra_args) if extra_args else ()
+    run_cmd = build_uv_run_command(skill_dir, manifest.runtime.entrypoint, args_tuple)
+    console.print(f"[dim]Running {manifest.name}...[/]")
+    result = subprocess.run(run_cmd, env=env)
+    raise typer.Exit(result.returncode)

dhub/cli/search.py

@@ -0,0 +1,36 @@
+"""CLI command for natural language skill search."""
+
+import httpx
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+
+def ask_command(
+    query: str = typer.Argument(help="Natural language query to search for skills"),
+) -> None:
+    """Search for skills using natural language.
+
+    Example: dhub ask "analyze A/B test results"
+    """
+    from dhub.cli.config import get_api_url, get_token
+
+    with httpx.Client(timeout=30) as client:
+        resp = client.get(
+            f"{get_api_url()}/v1/search",
+            params={"q": query},
+            headers={"Authorization": f"Bearer {get_token()}"},
+        )
+        if resp.status_code == 503:
+            console.print("[red]Search is not available (server not configured).[/]")
+            raise typer.Exit(1)
+        resp.raise_for_status()
+        data = resp.json()
+
+    console.print(Panel(
+        data["results"],
+        title=f"Results for: {data['query']}",
+        border_style="blue",
+    ))

dhub/core/__init__.py

@@ -0,0 +1 @@
+

dhub/core/install.py

@@ -0,0 +1,159 @@
+"""Installation utilities for skills.
+
+Handles checksum verification, canonical path resolution,
+and symlink management for linking skills to agent directories.
+"""
+
+import hashlib
+from pathlib import Path
+
+
+# Mapping of agent names to their skill directories
+AGENT_SKILL_PATHS: dict[str, Path] = {
+    "claude": Path.home() / ".claude" / "skills",
+    "cursor": Path.home() / ".cursor" / "skills",
+    "opencode": Path.home() / ".config" / "opencode" / "skills",
+    "gemini": Path.home() / ".gemini" / "skills",
+}
+
+
+def verify_checksum(data: bytes, expected: str) -> None:
+    """Verify that the SHA-256 checksum of data matches the expected value.
+
+    Args:
+        data: The raw bytes to hash.
+        expected: The expected hex-encoded SHA-256 digest.
+
+    Raises:
+        ValueError: If the computed checksum does not match.
+    """
+    actual = hashlib.sha256(data).hexdigest()
+    if actual != expected:
+        raise ValueError(
+            f"Checksum mismatch: expected {expected}, got {actual}."
+        )
+
+
+def get_dhub_skill_path(org: str, skill: str) -> Path:
+    """Return the canonical local path for an installed skill.
+
+    Args:
+        org: The organization slug.
+        skill: The skill name.
+
+    Returns:
+        Path to ~/.dhub/skills/{org}/{skill}/.
+    """
+    return Path.home() / ".dhub" / "skills" / org / skill
+
+
+def get_agent_skill_paths() -> dict[str, Path]:
+    """Return a copy of the mapping of agent names to their skill directories."""
+    return dict(AGENT_SKILL_PATHS)
+
+
+def link_skill_to_agent(org: str, skill_name: str, agent: str) -> Path:
+    """Create a symlink from the agent's skill directory to the canonical skill path.
+
+    The symlink is named {org}--{skill_name} inside the agent's skill directory,
+    and points to the canonical path under ~/.dhub/skills/{org}/{skill_name}/.
+
+    Args:
+        org: The organization slug.
+        skill_name: The skill name.
+        agent: The agent name (e.g. "claude", "cursor").
+
+    Returns:
+        The path of the created symlink.
+
+    Raises:
+        ValueError: If the agent name is not recognized.
+        FileNotFoundError: If the canonical skill directory does not exist.
+    """
+    if agent not in AGENT_SKILL_PATHS:
+        raise ValueError(
+            f"Unknown agent '{agent}'. Known agents: {', '.join(sorted(AGENT_SKILL_PATHS))}."
+        )
+
+    canonical = get_dhub_skill_path(org, skill_name)
+    if not canonical.exists():
+        raise FileNotFoundError(
+            f"Skill directory not found: {canonical}"
+        )
+
+    agent_dir = AGENT_SKILL_PATHS[agent]
+    agent_dir.mkdir(parents=True, exist_ok=True)
+
+    symlink_path = agent_dir / f"{org}--{skill_name}"
+
+    # Remove existing symlink if present to allow re-linking
+    if symlink_path.is_symlink() or symlink_path.exists():
+        symlink_path.unlink()
+
+    symlink_path.symlink_to(canonical)
+    return symlink_path
+
+
+def unlink_skill_from_agent(org: str, skill_name: str, agent: str) -> None:
+    """Remove the symlink for a skill from an agent's directory.
+
+    Args:
+        org: The organization slug.
+        skill_name: The skill name.
+        agent: The agent name.
+
+    Raises:
+        ValueError: If the agent name is not recognized.
+        FileNotFoundError: If no symlink exists for this skill/agent combination.
+    """
+    if agent not in AGENT_SKILL_PATHS:
+        raise ValueError(
+            f"Unknown agent '{agent}'. Known agents: {', '.join(sorted(AGENT_SKILL_PATHS))}."
+        )
+
+    symlink_path = AGENT_SKILL_PATHS[agent] / f"{org}--{skill_name}"
+
+    if not symlink_path.is_symlink() and not symlink_path.exists():
+        raise FileNotFoundError(
+            f"No symlink found at {symlink_path}"
+        )
+
+    symlink_path.unlink()
+
+
+def link_skill_to_all_agents(org: str, skill_name: str) -> list[str]:
+    """Symlink a skill to all known agent directories.
+
+    Args:
+        org: The organization slug.
+        skill_name: The skill name.
+
+    Returns:
+        List of agent names that were successfully linked.
+    """
+    linked: list[str] = []
+    for agent in sorted(AGENT_SKILL_PATHS):
+        link_skill_to_agent(org, skill_name, agent)
+        linked.append(agent)
+    return linked
+
+
+def list_linked_agents(org: str, skill_name: str) -> list[str]:
+    """Check which agents have a symlink for this skill.
+
+    Args:
+        org: The organization slug.
+        skill_name: The skill name.
+
+    Returns:
+        List of agent names that have a symlink pointing to this skill.
+    """
+    canonical = get_dhub_skill_path(org, skill_name)
+    linked: list[str] = []
+
+    for agent, agent_dir in sorted(AGENT_SKILL_PATHS.items()):
+        symlink_path = agent_dir / f"{org}--{skill_name}"
+        if symlink_path.is_symlink() and symlink_path.resolve() == canonical.resolve():
+            linked.append(agent)
+
+    return linked

dhub/core/manifest.py

@@ -0,0 +1,221 @@
+"""SKILL.md parser and validator.
+
+Parses SKILL.md files containing YAML frontmatter between --- delimiters
+followed by a markdown body that serves as the agent system prompt.
+"""
+
+import re
+from pathlib import Path
+
+import yaml
+
+from dhub.models import (
+    AgentTestTarget,
+    RuntimeConfig,
+    SkillManifest,
+    TestingConfig,
+)
+
+# Name: 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing hyphens.
+# Aligned with core/validation.py _SKILL_NAME_PATTERN.
+_NAME_PATTERN = re.compile(r"^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$")
+
+
+def parse_skill_md(path: Path) -> SkillManifest:
+    """Parse a SKILL.md file into a SkillManifest.
+
+    The file format is YAML frontmatter between --- delimiters,
+    followed by the markdown body (the agent system prompt).
+
+    Raises:
+        ValueError: If the file format is invalid or required fields are missing.
+        FileNotFoundError: If the path does not exist.
+    """
+    content = path.read_text()
+    frontmatter_str, body = _split_frontmatter(content)
+    data = yaml.safe_load(frontmatter_str)
+
+    if not isinstance(data, dict):
+        raise ValueError("Frontmatter must be a YAML mapping.")
+
+    # Required fields
+    name = data.get("name")
+    if not name:
+        raise ValueError("Required field 'name' is missing.")
+    if not isinstance(name, str) or not _NAME_PATTERN.match(name):
+        raise ValueError(
+            f"Invalid name '{name}': must be 1-64 chars, lowercase "
+            "alphanumeric + hyphens, no leading/trailing hyphens."
+        )
+
+    description = data.get("description")
+    if not description:
+        raise ValueError("Required field 'description' is missing.")
+    if not isinstance(description, str) or len(description) > 1024:
+        raise ValueError(
+            "Description must be a string of 1-1024 characters."
+        )
+
+    # Optional scalar fields
+    license_val = data.get("license")
+    compatibility = data.get("compatibility")
+    metadata = data.get("metadata")
+    allowed_tools = data.get("allowed_tools")
+
+    # Optional structured blocks
+    runtime = _parse_runtime(data.get("runtime"))
+    testing = _parse_testing(data.get("testing"))
+    manifest = SkillManifest(
+        name=name,
+        description=description,
+        license=license_val,
+        compatibility=compatibility,
+        metadata=metadata,
+        allowed_tools=allowed_tools,
+        runtime=runtime,
+        testing=testing,
+        body=body,
+    )
+
+    errors = validate_manifest(manifest)
+    if errors:
+        raise ValueError(
+            "Manifest validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+        )
+
+    return manifest
+
+
+def _split_frontmatter(content: str) -> tuple[str, str]:
+    """Split SKILL.md content into frontmatter string and body.
+
+    Expects the file to start with --- on its own line, followed by
+    YAML content, then another --- on its own line, then the body.
+    Uses line-based matching so that --- in the body (e.g. markdown
+    horizontal rules) does not break parsing.
+    """
+    lines = content.split("\n")
+
+    # Skip leading blank lines
+    start = 0
+    while start < len(lines) and lines[start].strip() == "":
+        start += 1
+
+    if start >= len(lines) or lines[start].strip() != "---":
+        raise ValueError(
+            "SKILL.md must start with --- to begin YAML frontmatter."
+        )
+
+    # Find the closing --- delimiter (must be on its own line)
+    close = None
+    for i in range(start + 1, len(lines)):
+        if lines[i].strip() == "---":
+            close = i
+            break
+
+    if close is None:
+        raise ValueError(
+            "SKILL.md must have closing --- delimiter after frontmatter."
+        )
+
+    frontmatter_str = "\n".join(lines[start + 1 : close])
+    body = "\n".join(lines[close + 1 :]).strip()
+    return frontmatter_str, body
+
+
+def _parse_runtime(data: dict | None) -> RuntimeConfig | None:
+    """Parse the runtime block from frontmatter."""
+    if data is None:
+        return None
+
+    if not isinstance(data, dict):
+        raise ValueError("'runtime' must be a mapping.")
+
+    driver = data.get("driver")
+    if not driver or not isinstance(driver, str):
+        raise ValueError("runtime.driver is required and must be a string.")
+
+    entrypoint = data.get("entrypoint")
+    if not entrypoint or not isinstance(entrypoint, str):
+        raise ValueError("runtime.entrypoint is required and must be a string.")
+
+    lockfile = data.get("lockfile")
+    if not lockfile or not isinstance(lockfile, str):
+        raise ValueError("runtime.lockfile is required and must be a string.")
+
+    env_raw = data.get("env", [])
+    if not isinstance(env_raw, list):
+        raise ValueError("runtime.env must be a list of strings.")
+    env = tuple(str(e) for e in env_raw)
+
+    return RuntimeConfig(
+        driver=driver,
+        entrypoint=entrypoint,
+        lockfile=lockfile,
+        env=env,
+    )
+
+
+def _parse_testing(data: dict | None) -> TestingConfig | None:
+    """Parse the testing block from frontmatter."""
+    if data is None:
+        return None
+
+    if not isinstance(data, dict):
+        raise ValueError("'testing' must be a mapping.")
+
+    cases = data.get("cases")
+    if not cases or not isinstance(cases, str):
+        raise ValueError("testing.cases is required and must be a string.")
+
+    agents_raw = data.get("agents", [])
+    if not isinstance(agents_raw, list):
+        raise ValueError("testing.agents must be a list.")
+
+    agents = tuple(_parse_agent_target(a) for a in agents_raw)
+
+    return TestingConfig(cases=cases, agents=agents)
+
+
+def _parse_agent_target(data: dict) -> AgentTestTarget:
+    """Parse a single agent test target from the testing.agents list."""
+    if not isinstance(data, dict):
+        raise ValueError("Each agent target must be a mapping.")
+
+    name = data.get("name")
+    if not name or not isinstance(name, str):
+        raise ValueError("Agent target 'name' is required.")
+
+    keys_raw = data.get("required_keys", [])
+    if not isinstance(keys_raw, list):
+        raise ValueError("Agent target 'required_keys' must be a list.")
+
+    return AgentTestTarget(
+        name=name,
+        required_keys=tuple(str(k) for k in keys_raw),
+    )
+
+
+def validate_manifest(manifest: SkillManifest) -> list[str]:
+    """Validate a parsed manifest. Returns list of error messages (empty = valid)."""
+    errors: list[str] = []
+
+    if not _NAME_PATTERN.match(manifest.name):
+        errors.append(
+            f"Invalid name '{manifest.name}': must be 1-64 chars, lowercase "
+            "alphanumeric + hyphens, no leading/trailing hyphens."
+        )
+
+    if not manifest.description or len(manifest.description) > 1024:
+        errors.append("Description must be 1-1024 characters.")
+
+    if not manifest.body:
+        errors.append("Body (system prompt) must not be empty.")
+
+    if manifest.runtime and manifest.runtime.driver not in ("local/uv",):
+        errors.append(
+            f"Unsupported runtime driver '{manifest.runtime.driver}'. "
+            "Supported: local/uv"
+        )
+
+    return errors

dhub/core/runtime.py

@@ -0,0 +1,84 @@
+"""Local uv runtime domain logic.
+
+Provides functions for validating prerequisites, building commands,
+and preparing environment variables for running skills via uv.
+"""
+
+import os
+import shutil
+from pathlib import Path
+
+from dhub.models import RuntimeConfig
+
+
+def validate_local_runtime_prerequisites(
+    skill_dir: Path, config: RuntimeConfig
+) -> list[str]:
+    """Check that all prerequisites for local runtime are met.
+
+    Returns a list of error messages. An empty list means all prerequisites
+    are satisfied.
+    """
+    errors: list[str] = []
+
+    if shutil.which("uv") is None:
+        errors.append(
+            "'uv' is not installed or not on PATH. "
+            "Install it from https://docs.astral.sh/uv/"
+        )
+
+    lockfile_path = skill_dir / config.lockfile
+    if not lockfile_path.exists():
+        errors.append(
+            f"Lockfile not found: {lockfile_path}"
+        )
+
+    entrypoint_path = skill_dir / config.entrypoint
+    if not entrypoint_path.exists():
+        errors.append(
+            f"Entrypoint not found: {entrypoint_path}"
+        )
+
+    return errors
+
+
+def build_uv_sync_command(skill_dir: Path) -> list[str]:
+    """Build the uv sync command for installing dependencies in a skill directory."""
+    return ["uv", "sync", "--directory", str(skill_dir)]
+
+
+def build_uv_run_command(
+    skill_dir: Path,
+    entrypoint: str,
+    extra_args: tuple[str, ...] = (),
+) -> list[str]:
+    """Build the uv run command for executing a skill entrypoint."""
+    cmd = ["uv", "run", "--directory", str(skill_dir), "python", entrypoint]
+    cmd.extend(extra_args)
+    return cmd
+
+
+def build_env_vars(
+    config: RuntimeConfig,
+    user_env: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Build environment variables dict from runtime config and user overrides.
+
+    Starts with the current process environment, overlays any user-provided
+    values, and validates that all required env vars (from config.env) are present.
+
+    Raises:
+        ValueError: If any required environment variable is missing.
+    """
+    env = dict(os.environ)
+
+    if user_env:
+        env.update(user_env)
+
+    missing = [var for var in config.env if var not in env]
+    if missing:
+        raise ValueError(
+            f"Missing required environment variables: {', '.join(missing)}"
+        )
+
+    return env

dhub/core/validation.py

@@ -0,0 +1,50 @@
+"""Validation functions for skill names and semver versions."""
+
+import re
+
+_SEMVER_PATTERN = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
+
+_SKILL_NAME_PATTERN = re.compile(r"^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$")
+
+
+def validate_semver(version: str) -> str:
+    """Validate that a version string follows semver format (major.minor.patch).
+
+    Args:
+        version: The version string to validate.
+
+    Returns:
+        The validated version string.
+
+    Raises:
+        ValueError: If the version does not match semver format.
+    """
+    if not _SEMVER_PATTERN.match(version):
+        raise ValueError(
+            f"Invalid semver '{version}': must be in major.minor.patch format "
+            "(e.g. '1.0.0')."
+        )
+    return version
+
+
+def validate_skill_name(name: str) -> str:
+    """Validate a skill name.
+
+    A valid skill name is 1-64 characters, lowercase alphanumeric plus hyphens,
+    with no leading or trailing hyphens.
+
+    Args:
+        name: The skill name to validate.
+
+    Returns:
+        The validated skill name.
+
+    Raises:
+        ValueError: If the name does not match the required format.
+    """
+    if not _SKILL_NAME_PATTERN.match(name):
+        raise ValueError(
+            f"Invalid skill name '{name}': must be 1-64 chars, lowercase "
+            "alphanumeric + hyphens, no leading/trailing hyphens."
+        )
+    return name

dhub/models.py

@@ -0,0 +1,38 @@
+"""Client-side domain models as frozen dataclasses."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SkillManifest:
+    """Parsed SKILL.md content."""
+    name: str
+    description: str
+    license: str | None
+    compatibility: str | None
+    metadata: dict[str, str] | None
+    allowed_tools: str | None
+    runtime: "RuntimeConfig | None"
+    testing: "TestingConfig | None"
+    body: str
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    driver: str
+    entrypoint: str
+    lockfile: str
+    env: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class AgentTestTarget:
+    name: str
+    required_keys: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class TestingConfig:
+    __test__ = False  # prevent pytest from trying to collect this dataclass
+    cases: str
+    agents: tuple[AgentTestTarget, ...]