autoplay-setup 0.1.0__py3-none-any.whl

autoplay_setup/__init__.py

@@ -0,0 +1,10 @@
+"""autoplay_setup — the pipx-installable wrapper CLI (PROJECT.md §5.1).
+
+Pure scripting, no AI logic: detects the project root, downloads the setup
+bundle, collects and validates PostHog credentials, then launches Claude Code
+from the project root to perform the actual integration.
+"""
+
+from autoplay_setup.__version__ import __version__
+
+__all__ = ["__version__"]

autoplay_setup/__version__.py

@@ -0,0 +1,8 @@
+"""Single source of version truth for the CLI (PROJECT.md §7 Versioning).
+
+This value is surfaced in the rendered CLAUDE.md and recorded in
+.autoplay/manifest.json so re-runs and support cases can pin exactly what
+shipped.
+"""
+
+__version__ = "0.1.0"

autoplay_setup/claude_code.py

@@ -0,0 +1,89 @@
+"""Detects, installs, and launches Claude Code (PROJECT.md §5.1.4, §5.1.8).
+
+Checks for `claude` on PATH (offering an npm install if missing) and launches it
+from the project root with our instructions via --append-system-prompt. Claude
+Code's output streams straight to the user's terminal (never captured).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+_NPM_PACKAGE = "@anthropic-ai/claude-code"
+
+# Pinned to a non-1M-context model: the default Opus 1M variant 429s on
+# plans without long-context credits ("usage credits required"). Sonnet
+# handles the setup procedure reliably. Overridable via the --model flag.
+DEFAULT_MODEL = "sonnet"
+
+# First user turn. `--append-system-prompt` alone gives the agent context
+# but no message to act on, so it sits idle. Passing this as a positional
+# prompt keeps the session interactive (only -p/--print is headless) while
+# auto-starting the skill — the confirmation prompts still work.
+_KICKOFF_PROMPT = (
+    "Begin the Autoplay setup now: read ./.autoplay/task.md, then load and "
+    "follow ./.autoplay/skills/posthog-setup/SKILL.md exactly. Confirm with me "
+    "before every external write."
+)
+
+
+def check_installed() -> bool:
+    """Return True if the `claude` CLI is on PATH."""
+    return shutil.which("claude") is not None
+
+
+def install_via_npm() -> bool:
+    """Install Claude Code globally via npm.
+
+    Returns:
+        True if installation succeeded, False otherwise (incl. missing npm).
+    """
+    if shutil.which("npm") is None:
+        return False
+    result = subprocess.run(
+        ["npm", "install", "-g", _NPM_PACKAGE],
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def launch(
+    project_root: Path,
+    claude_md_path: Path,
+    *,
+    model: str = DEFAULT_MODEL,
+    kickoff: str = _KICKOFF_PROMPT,
+) -> int:
+    """Launch Claude Code from the project root with our instructions.
+
+    Runs from the customer's project root (NOT .autoplay/) so the agent can
+    edit real source while following our appended system prompt. Output is not
+    captured — it streams to the terminal.
+
+    Args:
+        project_root: The customer's project root (used as cwd).
+        claude_md_path: Path to the rendered CLAUDE.md to append.
+        model: Model alias/name to pin (avoids the 1M-context credit gate).
+        kickoff: Positional first-turn prompt that auto-starts the skill.
+
+    Returns:
+        Claude Code's process exit code.
+    """
+    claude_md = claude_md_path.read_text(encoding="utf-8")
+    # No --dangerously-skip-permissions: Claude Code prompts the user to approve
+    # each command/edit. The customer stays in control of every action.
+    result = subprocess.run(
+        [
+            "claude",
+            "--model",
+            model,
+            "--append-system-prompt",
+            claude_md,
+            kickoff,
+        ],
+        cwd=str(project_root),
+        check=False,
+    )
+    return result.returncode

autoplay_setup/credentials.py

@@ -0,0 +1,209 @@
+"""Interactive credential collection (PROJECT.md §5.1.5).
+
+Walks the customer through host selection, the three PostHog keys/IDs, and the
+inline validation loop, re-prompting only the fields relevant to each failure
+so a bad input never kills the CLI. Secrets are never logged or shown.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
+
+from autoplay_setup.env_detector import detect_posthog_host
+from autoplay_setup.errors import PostHogValidationError, UserAbortedError
+from autoplay_setup.host import parse_host
+from autoplay_setup.posthog_validator import ValidationResult, validate_credentials
+
+Validator = Callable[[str, str, str], Awaitable[ValidationResult]]
+
+
+@dataclass
+class Credentials:
+    """Validated PostHog credentials.
+
+    Attributes:
+        host: Normalized PostHog host URL.
+        project_id: PostHog project id.
+        project_api_key: Project API key (phc_...); excluded from repr.
+        personal_api_key: Personal API key (phx_...); excluded from repr.
+    """
+
+    host: str
+    project_id: str
+    project_api_key: str = field(repr=False)
+    personal_api_key: str = field(repr=False)
+    project_name: str = ""
+
+
+def _prompt_host(detected: str | None, console: Console) -> str:
+    """Prompt for the host (with detected default) until it parses."""
+    if detected:
+        console.print(
+            f"    [dim]Found [bold]{detected}[/bold] in your code — press "
+            f"Enter to use it.[/dim]"
+        )
+    else:
+        console.print(
+            "    [dim]The API host your app sends events to. Just type "
+            "[bold]us[/bold] or [bold]eu[/bold] for PostHog Cloud "
+            "([bold]https://us.posthog.com[/bold] / "
+            "[bold]https://eu.posthog.com[/bold]), or your own URL if "
+            "self-hosted.[/dim]"
+        )
+    while True:
+        suffix = f" [detected: {detected}]" if detected else ""
+        raw = Prompt.ask(f"PostHog host{suffix}", default=detected or None)
+        try:
+            return parse_host(raw or "")
+        except ValueError as exc:
+            console.print(Panel(str(exc), title="Invalid host", style="red"))
+
+
+def _settings_host(host: str) -> str:
+    """Map a PostHog API host to the app host that serves the settings UI.
+
+    Cloud uses the `*.i.posthog.com` ingestion host for API/events but serves
+    settings (where personal API keys are created) on `*.posthog.com`. For
+    self-hosted, the API and app host are the same.
+    """
+    return host.replace("us.i.posthog.com", "us.posthog.com").replace(
+        "eu.i.posthog.com", "eu.posthog.com"
+    )
+
+
+def _print_project_id_help(host: str, console: Console) -> None:
+    app = _settings_host(host)
+    console.print(
+        f"    [dim]Your numeric Project ID. Find it under "
+        f"[bold]{app}/settings/project[/bold] ('Project ID'), or read it "
+        f"straight from your PostHog URL — the number in "
+        f"[bold]{app}/project/<ID>[/bold].[/dim]"
+    )
+
+
+def _print_project_key_help(host: str, console: Console) -> None:
+    app = _settings_host(host)
+    console.print(
+        f"    [dim]The public [bold]Project API Key[/bold] (starts "
+        f"[bold]phc_[/bold]) from [bold]{app}/settings/project[/bold] — the "
+        f"same token already in your posthog.init(...) snippet. Safe to expose "
+        f"in client code.[/dim]"
+    )
+
+
+def _print_personal_key_help(host: str, console: Console) -> None:
+    console.print(
+        f"    [dim]A private key (starts [bold]phx_[/bold]) that lets us read "
+        f"your project and create the Autoplay destination. Create one at "
+        f"[bold]{_settings_host(host)}/settings/user-api-keys[/bold] → "
+        f"'New personal API key'. Easiest is scope [bold]All access[/bold]; if "
+        f"you'd rather narrow it, include [bold]project:read[/bold] and "
+        f"[bold]hog_function:write[/bold], scoped to this project.[/dim]"
+    )
+
+
+def _render_error(result: ValidationResult, console: Console) -> None:
+    messages = {
+        "host_unreachable": "Can't reach that host. Check the URL and your "
+        "network; if self-hosted, confirm the server is up.",
+        "project_not_found": "Got a 404 for that project. Either the Project "
+        "ID is wrong, or your Personal API Key can't see this project — make "
+        "sure the key has the [bold]project:read[/bold] scope and is scoped "
+        "to this project (or all projects). Confirm the ID at "
+        "Settings → Project.",
+        "auth_failed": "That personal API key was rejected. Make sure you "
+        "used a Personal API Key (phx_...), not the Project API Key (phc_...).",
+    }
+    detail = messages.get(result.status, "Validation failed.")
+    console.print(Panel(detail, title="Validation failed", style="red"))
+
+
+async def collect_and_validate(
+    project_root: Path,
+    console: Console | None = None,
+    validator: Validator = validate_credentials,
+) -> Credentials:
+    """Collect and live-validate PostHog credentials (PROJECT.md §5.1.5).
+
+    Args:
+        project_root: The customer's project root (used for host detection).
+        console: Optional Rich console.
+        validator: Async validation function (injectable for tests).
+
+    Returns:
+        Validated Credentials.
+
+    Raises:
+        UserAbortedError: If the user presses Ctrl-C.
+        PostHogValidationError: On an unrecoverable (unknown) validation error.
+    """
+    console = console or Console()
+    detected = detect_posthog_host(project_root)
+    console.print(
+        "    I need 4 things from PostHog: your [bold]host[/bold], "
+        "[bold]Project ID[/bold], [bold]Project API Key[/bold], and a "
+        "[bold]Personal API Key[/bold]. I'll point you to each one."
+    )
+
+    host: str | None = None
+    project_id: str | None = None
+    project_api_key: str | None = None
+    personal_api_key: str | None = None
+
+    try:
+        while True:
+            if host is None:
+                host = _prompt_host(detected, console)
+            if project_id is None:
+                _print_project_id_help(host, console)
+                project_id = Prompt.ask("PostHog Project ID")
+            if project_api_key is None:
+                _print_project_key_help(host, console)
+                while not project_api_key:
+                    project_api_key = Prompt.ask(
+                        "PostHog Project API Key (phc_...)", password=True
+                    )
+                    if not project_api_key:
+                        console.print(
+                            "[yellow]Project API Key is required.[/yellow]"
+                        )
+            if personal_api_key is None:
+                _print_personal_key_help(host, console)
+                personal_api_key = Prompt.ask(
+                    "PostHog Personal API Key (phx_...)", password=True
+                )
+
+            result = await validator(host, project_id, personal_api_key)
+            if result.status == "success":
+                return Credentials(
+                    host=host,
+                    project_id=project_id,
+                    project_api_key=project_api_key,
+                    personal_api_key=personal_api_key,
+                    project_name=getattr(result, "project_name", ""),
+                )
+
+            _render_error(result, console)
+            if result.status == "host_unreachable":
+                host = None
+            elif result.status == "project_not_found":
+                # The host responded (not unreachable), so keep it. A 404 means
+                # either the project id is wrong or the key can't see it —
+                # re-prompt both.
+                project_id = None
+                personal_api_key = None
+            elif result.status == "auth_failed":
+                personal_api_key = None
+            else:
+                raise PostHogValidationError(
+                    "unknown", f"HTTP {result.status_code}"
+                )
+    except KeyboardInterrupt as exc:
+        message = "Setup cancelled during credential entry."
+        raise UserAbortedError(message) from exc

autoplay_setup/download.py

@@ -0,0 +1,108 @@
+"""Bundle download from the token server (PROJECT.md §5.1.3).
+
+Fetches the zip from the token server's one-time download endpoint, validates
+its contents, and unpacks it into ./.autoplay/ (prompting before overwriting an
+existing directory).
+"""
+
+from __future__ import annotations
+
+import io
+import shutil
+import zipfile
+from pathlib import Path
+
+import httpx
+from rich.console import Console
+from rich.prompt import Confirm
+
+from autoplay_setup.errors import (
+    AutoplaySetupError,
+    TokenNotFoundError,
+    UserAbortedError,
+)
+
+_TIMEOUT_SECONDS = 30.0
+
+# Files every valid bundle must contain (PROJECT.md §6.5 / §5.3).
+_REQUIRED_FILES = {"CLAUDE.md", "task.md", "manifest.json", ".env.example"}
+_REQUIRED_PREFIX = "skills/posthog-setup/"
+
+
+def _corrupt_download() -> AutoplaySetupError:
+    return AutoplaySetupError(
+        message="The downloaded setup bundle looks corrupt or incomplete.",
+        exit_code=2,
+        remediation=(
+            "Generate a fresh setup token and try again. If it keeps "
+            "happening, contact support with your setup session id."
+        ),
+    )
+
+
+def _validate_members(names: list[str]) -> None:
+    """Reject unsafe paths and ensure the bundle has the required files."""
+    for name in names:
+        if name.startswith("/") or ".." in Path(name).parts:
+            raise _corrupt_download()
+    present = set(names)
+    if not _REQUIRED_FILES.issubset(present):
+        raise _corrupt_download()
+    if not any(name.startswith(_REQUIRED_PREFIX) for name in names):
+        raise _corrupt_download()
+
+
+async def download_setup_package(
+    server_url: str,
+    token: str,
+    target_dir: Path,
+    console: Console | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> None:
+    """Download, validate, and unpack the setup bundle into target_dir.
+
+    Args:
+        server_url: Base URL of the token server.
+        token: One-time setup token.
+        target_dir: Directory to unpack into (e.g. project/.autoplay).
+        console: Optional Rich console.
+        client: Optional injected httpx client (for tests).
+
+    Raises:
+        TokenNotFoundError: If the server returns 404.
+        UserAbortedError: If the user declines to overwrite an existing dir.
+        AutoplaySetupError: If the download fails or the bundle is corrupt.
+    """
+    console = console or Console()
+
+    if target_dir.exists() and any(target_dir.iterdir()):
+        if not Confirm.ask(
+            f"{target_dir} already exists. Overwrite it?", default=False
+        ):
+            raise UserAbortedError(f"Left existing {target_dir} untouched.")
+
+    url = f"{server_url.rstrip('/')}/setup/{token}/download"
+    owns_client = client is None
+    client = client or httpx.AsyncClient(timeout=_TIMEOUT_SECONDS)
+    try:
+        response = await client.get(url)
+    finally:
+        if owns_client:
+            await client.aclose()
+
+    if response.status_code == 404:
+        raise TokenNotFoundError()
+    if response.status_code != 200:
+        raise _corrupt_download()
+
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(response.content))
+    except zipfile.BadZipFile as exc:
+        raise _corrupt_download() from exc
+
+    _validate_members(archive.namelist())
+
+    if target_dir.exists():
+        shutil.rmtree(target_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    archive.extractall(target_dir)

autoplay_setup/env_detector.py

@@ -0,0 +1,78 @@
+"""Detects existing PostHog config in the customer's project (§5.1.5a).
+
+Best-effort scan of .env files and framework configs for an existing PostHog
+host (or a posthog.init api_host) to offer as the suggested default. Never
+raises — detection is convenience, not authority.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_ENV_FILES = (".env", ".env.local", ".env.example")
+_ENV_KEYS = ("POSTHOG_HOST", "NEXT_PUBLIC_POSTHOG_HOST", "VITE_POSTHOG_HOST")
+_JS_CONFIGS = ("next.config.js", "vite.config.ts", "nuxt.config.ts")
+
+# KEY=value (optionally quoted) on a single env line.
+_ENV_LINE = re.compile(r"^\s*(?P<key>[A-Z0-9_]+)\s*=\s*(?P<val>.+?)\s*$")
+# api_host: "https://..."  inside a posthog.init(...) style config.
+_API_HOST = re.compile(r"""api_host\s*:\s*['"](?P<val>[^'"]+)['"]""")
+
+
+def _strip_quotes(value: str) -> str:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    return value
+
+
+def _scan_env_file(path: Path) -> str | None:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    values: dict[str, str] = {}
+    for line in text.splitlines():
+        if line.lstrip().startswith("#"):
+            continue
+        match = _ENV_LINE.match(line)
+        if match:
+            values[match.group("key")] = _strip_quotes(match.group("val"))
+    for key in _ENV_KEYS:
+        if key in values and values[key]:
+            return values[key]
+    return None
+
+
+def _scan_js_config(path: Path) -> str | None:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    match = _API_HOST.search(text)
+    return match.group("val") if match else None
+
+
+def detect_posthog_host(project_root: Path) -> str | None:
+    """Find a likely PostHog host already configured in the project.
+
+    Args:
+        project_root: The customer's project root directory.
+
+    Returns:
+        The first host value found, or None. Env files are checked before
+        framework configs; never raises.
+    """
+    try:
+        for name in _ENV_FILES:
+            found = _scan_env_file(project_root / name)
+            if found:
+                return found
+        for name in _JS_CONFIGS:
+            found = _scan_js_config(project_root / name)
+            if found:
+                return found
+    except Exception:
+        return None
+    return None

autoplay_setup/env_writer.py

@@ -0,0 +1,65 @@
+"""Atomic .env writer with 0600 permissions (PROJECT.md §5.1.5e, §6.2, §7).
+
+Writes ./.autoplay/.env atomically (temp file + rename) with owner-only
+permissions, splitting the user-provided values from the Autoplay values Claude
+Code fills in later. Secrets are never logged.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+# Autoplay values Claude Code fills in during the run (PROJECT.md §6.2).
+_AUTOPLAY_PLACEHOLDERS = (
+    "AUTOPLAY_CONNECTOR_URL",
+    "AUTOPLAY_STREAM_URL",
+    "AUTOPLAY_WEBHOOK_SECRET",
+    "AUTOPLAY_UNKEY_TOKEN",
+)
+
+
+def _quote(value: str) -> str:
+    """Quote a value for a .env line, escaping backslashes and quotes."""
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _render(env_vars: dict[str, str]) -> str:
+    """Render the full .env content with both sections."""
+    lines = ["# Provided by user (CLI)"]
+    lines += [f"{key}={_quote(val)}" for key, val in env_vars.items()]
+    lines.append("")
+    lines.append("# Filled in by Claude Code during the run")
+    # AUTOPLAY_PRODUCT_ID always mirrors POSTHOG_PROJECT_ID (PROJECT.md §6.2).
+    project_id = env_vars.get("POSTHOG_PROJECT_ID", "")
+    lines.append(f"AUTOPLAY_PRODUCT_ID={_quote(project_id)}")
+    lines += [f"{key}={_quote('')}" for key in _AUTOPLAY_PLACEHOLDERS]
+    return "\n".join(lines) + "\n"
+
+
+def write_env_file(path: Path, env_vars: dict[str, str]) -> None:
+    """Atomically write a 0600 .env file with the given user values.
+
+    Args:
+        path: Destination path (e.g. .autoplay/.env).
+        env_vars: User-provided values (POSTHOG_*). The Autoplay section is
+            scaffolded with empty placeholders for Claude Code to fill in.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    content = _render(env_vars)
+
+    fd, tmp_name = tempfile.mkstemp(
+        dir=str(path.parent), prefix=".env.", suffix=".tmp"
+    )
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(content)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        if tmp.exists():
+            tmp.unlink()
+        raise