Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

2.9 KB
Raw Blame
"""Shared format for sandbox addons (tools, MCP servers): named entries chosen
from a checked-in YAML catalog into a per-user YAML file. Owns the read/write
plumbing, the registry path, and the error type; per-type schema and apply logic
live in sandbox_tools.py / sandbox_mcp.py.
"""

from __future__ import annotations

from collections.abc import Callable
from pathlib import Path
from typing import Protocol, TypeVar

import yaml

REGISTRY_DIR = Path.home() / ".posthog-sandboxes"


class AddonError(Exception):
    """Raised on any malformed catalog or user-file entry."""


class _Named(Protocol):
    name: str


_T = TypeVar("_T", bound=_Named)


class _BlockLiteralDumper(yaml.SafeDumper):
    """Renders multi-line strings as `|` blocks (e.g. tool install scripts)."""


def _block_literal_str(dumper: yaml.SafeDumper, data: str) -> yaml.ScalarNode:
    style = "|" if "\n" in data else None
    return dumper.represent_scalar("tag:yaml.org,2002:str", data, style=style)


_BlockLiteralDumper.add_representer(str, _block_literal_str)


def load_named_entries(path: Path, section: str) -> list[dict]:
    """Read the `section:` list as raw dicts, validating unique non-empty names.

    Returns [] when the file is absent.
    """
    if not path.is_file():
        return []
    raw = yaml.safe_load(path.read_text()) or {}
    entries: list[dict] = []
    seen: set[str] = set()
    for i, entry in enumerate(raw.get(section) or []):
        label = f"{path}: {section}[{i}]"
        if not isinstance(entry, dict):
            raise AddonError(f"{label}: must be a mapping.")
        name = entry.get("name")
        if not isinstance(name, str) or not name.strip():
            raise AddonError(f"{label}: 'name' is required and must be a non-empty string.")
        if name in seen:
            raise AddonError(f"{path}: duplicate name {name!r}.")
        seen.add(name)
        entries.append(entry)
    return entries


def save_named_entries(path: Path, section: str, entries: list[dict], *, mode: int | None = None) -> None:
    """Write `entries` under the `section:` key, preserving order and block scalars."""
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        yaml.dump(
            {section: entries},
            Dumper=_BlockLiteralDumper,
            sort_keys=False,
            default_flow_style=False,
            indent=2,
        )
    )
    if mode is not None:
        path.chmod(mode)


def load_entries(path: Path, section: str, parse: Callable[[dict], _T]) -> list[_T]:
    """Parse each `section:` entry from a YAML file into a typed object."""
    return [parse(entry) for entry in load_named_entries(path, section)]


def load_catalog(path: Path, section: str, parse: Callable[[dict], _T]) -> dict[str, _T]:
    """Like load_entries, but keyed by entry name for catalog lookups."""
    return {entry.name: entry for entry in load_entries(path, section, parse)}