phlo-clickstack 0.2.0__tar.gz → 0.3.0__tar.gz

{phlo_clickstack-0.2.0 → phlo_clickstack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phlo-clickstack
-Version: 0.2.0
+Version: 0.3.0
 Summary: clickstack service plugin for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT

{phlo_clickstack-0.2.0 → phlo_clickstack-0.3.0}/pyproject.toml

@@ -1,21 +1,35 @@
 [build-system]
-requires = ["setuptools>=45", "wheel"]
 build-backend = "setuptools.build_meta"
+requires = [
+    "setuptools>=45",
+    "wheel",
+]
 
 [project]
-name = "phlo-clickstack"
-version = "0.2.0"
-description = "clickstack service plugin for Phlo"
-readme = {text = "clickstack service plugin for Phlo.", content-type = "text/plain"}
-requires-python = ">=3.11"
-authors = [
-    {name = "Phlo Team", email = "team@phlo.dev"},
-]
-license = {text = "MIT"}
 dependencies = [
     "phlo>=0.1.0",
     "pyyaml>=6.0.1",
 ]
+description = "clickstack service plugin for Phlo"
+name = "phlo-clickstack"
+requires-python = ">=3.11"
+version = "0.3.0"
+
+[[project.authors]]
+email = "team@phlo.dev"
+name = "Phlo Team"
+
+[project.entry-points."phlo.plugins.cli"]
+clickstack = "phlo_clickstack.cli_plugin:ClickStackCliPlugin"
+
+[project.entry-points."phlo.plugins.resources"]
+clickstack = "phlo_clickstack.resource_provider:ClickStackResourceProvider"
+
+[project.entry-points."phlo.plugins.services"]
+clickstack = "phlo_clickstack.plugin:ClickStackServicePlugin"
+
+[project.license]
+text = "MIT"
 
 [project.optional-dependencies]
 dev = [
@@ -23,22 +37,22 @@ dev = [
     "ruff>=0.1.0",
 ]
 
-[project.entry-points."phlo.plugins.services"]
-clickstack = "phlo_clickstack.plugin:ClickStackServicePlugin"
+[project.readme]
+content-type = "text/plain"
+text = "clickstack service plugin for Phlo."
 
-[project.entry-points."phlo.plugins.cli"]
-clickstack = "phlo_clickstack.cli_plugin:ClickStackCliPlugin"
+[tool.ruff]
+line-length = 100
+target-version = "py311"
 
 [tool.setuptools]
-package-dir = {"" = "src"}
 include-package-data = true
 
-[tool.setuptools.packages.find]
-where = ["src"]
-
 [tool.setuptools.package-data]
 phlo_clickstack = ["service.yaml"]
 
-[tool.ruff]
-line-length = 100
-target-version = "py311"
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]

phlo_clickstack-0.3.0/src/phlo_clickstack/__init__.py

@@ -0,0 +1,21 @@
+"""Phlo ClickStack package for observability backend.
+
+This package provides a ClickStack service plugin for Phlo, bundling
+ClickHouse for observability data storage and querying.
+
+Exports:
+    ClickStackServicePlugin: Service plugin for ClickStack.
+    ClickStackCliPlugin: CLI plugin for ClickStack commands.
+    ClickStackSurfaceAdapter: Regulated surface adapter for ClickStack CLI.
+    get_clickstack_adapter: Get the ClickStack surface adapter singleton.
+"""
+
+from phlo_clickstack.authorization import (
+    ClickStackSurfaceAdapter,
+    get_adapter as get_clickstack_adapter,
+)
+
+__all__ = [
+    "ClickStackSurfaceAdapter",
+    "get_clickstack_adapter",
+]

phlo_clickstack-0.3.0/src/phlo_clickstack/authorization.py

@@ -0,0 +1,166 @@
+"""Regulated surface adapter for ClickStack CLI.
+
+This module provides the regulated surface adapter for the ClickStack CLI,
+declaring mutation commands that require authorization and enforcing
+through core enforcement.
+
+Mutation commands (require authorization):
+- clickstack.query
+
+Read commands (no authorization):
+- (none currently)
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any
+
+from phlo.cli.authorization import CliPrincipalResolver
+from phlo.logging import get_logger
+from phlo.security.adapters import (
+    EnforcementResult,
+    SurfaceOperation,
+)
+from phlo.security.enforcement import enforce
+
+logger = get_logger(__name__)
+
+SURFACE_NAME = "phlo-clickstack"
+FRAMEWORK_TYPE = "cli"
+
+MUTATION_COMMANDS: frozenset[str] = frozenset(
+    {
+        "clickstack.query",
+    }
+)
+
+READ_COMMANDS: frozenset[str] = frozenset()
+
+COMMAND_RESOURCE_MAP: dict[str, str] = {
+    "clickstack.query": "dataset",
+}
+
+COMMAND_ACTION_MAP: dict[str, str] = {
+    "clickstack.query": "dataset.write",
+}
+
+
+class ClickStackSurfaceAdapter:
+    """Regulated surface adapter for ClickStack CLI.
+
+    Declares mutation commands and enforces authorization through core
+    enforcement for privileged operations.
+    """
+
+    _instance: ClickStackSurfaceAdapter | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._resolver = CliPrincipalResolver()
+
+    @classmethod
+    def get_instance(cls) -> ClickStackSurfaceAdapter:
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    @property
+    def surface_name(self) -> str:
+        return SURFACE_NAME
+
+    @property
+    def framework_type(self) -> str:
+        return FRAMEWORK_TYPE
+
+    def list_operations(self) -> list[SurfaceOperation]:
+        operations: list[SurfaceOperation] = []
+        for command in MUTATION_COMMANDS:
+            resource_type = COMMAND_RESOURCE_MAP.get(command, "dataset")
+            action = COMMAND_ACTION_MAP.get(command, f"clickstack.{command}")
+            operations.append(
+                SurfaceOperation(
+                    action=action,
+                    resource_type=resource_type,
+                    operation_name=command,
+                    resource_id_strategy=None,
+                    framework_metadata={"command": command},
+                )
+            )
+        return operations
+
+    def is_active(self, runtime: Any) -> bool:
+        return True
+
+    def install(self, runtime: Any) -> None:
+        pass
+
+    def enforce_mutation(self, command: str, resource_id: str | None = None) -> EnforcementResult:
+        """Enforce authorization for a mutation command."""
+        if command not in MUTATION_COMMANDS:
+            return EnforcementResult.allow()
+
+        action = COMMAND_ACTION_MAP.get(command, f"clickstack.{command}")
+        resource_type = COMMAND_RESOURCE_MAP.get(command, "dataset")
+        resource_id_final = resource_id or f"clickstack:{command}"
+
+        principal = self._resolver.resolve()
+
+        from phlo.capabilities.interfaces import ResourceRef
+
+        resource = ResourceRef(
+            resource_type=resource_type,
+            resource_id=resource_id_final,
+        )
+
+        request_id = os.environ.get("PHLO_REQUEST_ID")
+
+        result = enforce(
+            principal=principal,
+            action=action,
+            resource=resource,
+            context=None,
+            request_id=request_id,
+            surface=SURFACE_NAME,
+        )
+
+        logger.debug(
+            "clickstack_mutation_enforcement_result",
+            command=command,
+            action=action,
+            result=result.variant,
+            subject=principal.subject,
+        )
+
+        return result
+
+    def check_command_authorization(self, command_path: str) -> EnforcementResult:
+        """Check if a command is authorized to run."""
+        if command_path in READ_COMMANDS:
+            return EnforcementResult.allow()
+
+        if command_path in MUTATION_COMMANDS:
+            return self.enforce_mutation(command_path)
+
+        logger.warning(
+            "clickstack_unknown_command_classification",
+            command=command_path,
+        )
+        return EnforcementResult.deny(
+            reason_code="unknown_command",
+            explanation=f"Command '{command_path}' is not classified as read or mutation",
+        )
+
+
+_adapter: ClickStackSurfaceAdapter | None = None
+
+
+def get_adapter() -> ClickStackSurfaceAdapter:
+    """Get the singleton ClickStack surface adapter."""
+    global _adapter
+    if _adapter is None:
+        _adapter = ClickStackSurfaceAdapter()
+    return _adapter

{phlo_clickstack-0.2.0 → phlo_clickstack-0.3.0}/src/phlo_clickstack/cli.py

@@ -1,13 +1,19 @@
-"""CLI commands for querying ClickStack's bundled ClickHouse service."""
+"""CLI commands for querying ClickStack's bundled ClickHouse service.
+
+This module provides Click CLI commands for executing SQL queries against
+the running ClickStack ClickHouse container. It includes utilities for
+validating container backend availability, reading SQL from files or inline arguments,
+and executing queries with configurable formatting.
+"""
 
 from __future__ import annotations
 
 from pathlib import Path
-from shutil import which
 from subprocess import TimeoutExpired
 
 import click
 
+from phlo.cli.commands.services import utils as services_utils
 from phlo.cli.infrastructure.command import CommandError, run_command
 from phlo.cli.infrastructure.compose import compose_base_cmd
 from phlo.cli.infrastructure.utils import get_project_name
@@ -17,7 +23,26 @@ logger = get_logger(__name__)
 
 
 def _read_query(*, query: str | None, file: Path | None) -> str:
-    """Return SQL text from inline query or file input."""
+    """Read and validate SQL query from inline argument or file.
+
+    Accepts either an inline SQL query string or a path to a SQL file.
+    Validates that exactly one input source is provided and that the
+    content is non-empty.
+
+    Args:
+        query: Inline SQL query string, or None if reading from file.
+        file: Path to SQL file, or None if using inline query.
+
+    Returns:
+        str: The SQL query text to execute.
+
+    Raises:
+        click.ClickException: If both query and file are provided.
+        click.ClickException: If file cannot be read.
+        click.ClickException: If file is empty or contains only whitespace.
+        click.ClickException: If neither query nor file is provided.
+
+    """
     if query and file:
         raise click.ClickException("Use either an inline query or --file, not both.")
     if file is not None:
@@ -34,34 +59,36 @@ def _read_query(*, query: str | None, file: Path | None) -> str:
 
 
 def _ensure_phlo_dir() -> Path:
-    """Return the local .phlo directory or exit with a clear error."""
+    """Locate and return the local .phlo directory.
+
+    Searches for a .phlo directory in the current working directory.
+    This directory is required for Docker Compose project configuration.
+
+    Returns:
+        Path: Path to the .phlo directory.
+
+    Raises:
+        click.ClickException: If .phlo directory does not exist.
+
+    """
     phlo_dir = Path.cwd() / ".phlo"
     if phlo_dir.exists():
         return phlo_dir
     raise click.ClickException(".phlo directory not found. Run 'phlo services init' first.")
 
 
-def _require_docker() -> None:
-    """Validate that Docker is installed and responsive."""
-    if which("docker") is None:
-        raise click.ClickException("docker command not found.")
-    try:
-        result = run_command(
-            ["docker", "info"],
-            timeout_seconds=10,
-            capture_output=True,
-            check=False,
-        )
-    except TimeoutExpired as exc:
-        raise click.ClickException("docker info timed out.") from exc
-    if result.returncode == 0:
-        return
-    raise click.ClickException("Docker is not running.")
+def _require_container_backend() -> None:
+    """Validate that the selected container backend is available."""
+    services_utils.require_container_backend()
 
 
 @click.group(name="clickstack")
 def clickstack_group() -> None:
-    """Query and inspect the ClickStack service."""
+    """Query and inspect the ClickStack service.
+
+    Provides commands for interacting with the ClickStack ClickHouse
+    container, including executing SQL queries.
+    """
 
 
 @clickstack_group.command(name="query")
@@ -75,8 +102,28 @@ def clickstack_query(
     output_format: str,
     timeout_seconds: int,
 ) -> None:
-    """Execute a ClickHouse query against the running ClickStack service."""
-    _require_docker()
+    """Execute a ClickHouse query against the running ClickStack service.
+
+    Runs a SQL query via clickhouse-client inside the ClickStack container.
+    Accepts SQL either as a command argument or from a file. Requires Docker
+    and a running phlo services stack with ClickStack enabled.
+
+    Args:
+        query: SQL query string to execute.
+        query_file: Path to file containing SQL query.
+        output_format: ClickHouse output format (default: TabSeparatedRaw).
+        timeout_seconds: Query execution timeout in seconds.
+
+    Raises:
+        click.ClickException: If Docker is unavailable.
+        click.ClickException: If .phlo directory is missing.
+        click.ClickException: If both query and file options provided.
+        click.ClickException: If query file cannot be read.
+        click.ClickException: If query execution fails.
+        click.ClickException: If query times out.
+
+    """
+    _require_container_backend()
     phlo_dir = _ensure_phlo_dir()
     project_name = get_project_name()
     sql = _read_query(query=query, file=query_file)

phlo_clickstack-0.3.0/src/phlo_clickstack/cli_plugin.py

@@ -0,0 +1,49 @@
+"""CLI plugin for ClickStack commands.
+
+This module defines the ClickStackCliPlugin class which registers CLI commands
+for interacting with the ClickStack ClickHouse service.
+"""
+
+from __future__ import annotations
+
+import click
+
+from phlo.plugins.base import CliCommandPlugin, PluginMetadata
+
+from phlo_clickstack.cli import clickstack_group
+
+
+class ClickStackCliPlugin(CliCommandPlugin):
+    """Register ClickStack CLI commands.
+
+    This plugin provides CLI commands for querying and managing the
+    ClickStack ClickHouse service instance.
+
+    Example:
+        Registered automatically when phlo_clickstack is installed.
+        Use `phlo clickstack --help` to see available commands.
+
+    """
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for ClickStack CLI registration.
+
+        Returns:
+            PluginMetadata: Metadata including name, version, and description.
+
+        """
+        return PluginMetadata(
+            name="clickstack",
+            version="0.1.0",
+            description="CLI commands for ClickStack query access",
+        )
+
+    def get_cli_commands(self) -> list[click.Command]:
+        """Return ClickStack CLI commands.
+
+        Returns:
+            list[click.Command]: List of Click commands provided by this plugin.
+
+        """
+        return [clickstack_group]

phlo_clickstack-0.3.0/src/phlo_clickstack/observability_backend.py

@@ -0,0 +1,148 @@
+"""ClickStack-backed observability capability provider."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import requests
+
+from phlo.capabilities import (
+    CapabilitySupport,
+    DefaultObservabilityBackend,
+    ObservabilityBackendSpec,
+    TraceSpan,
+    TraceSpanFilter,
+)
+
+_CLICKSTACK_QUERY_URL_ENV = "CLICKSTACK_QUERY_URL"
+_CLICKSTACK_QUERY_USER_ENV = "CLICKSTACK_QUERY_USER"
+_CLICKSTACK_QUERY_PASSWORD_ENV = "CLICKSTACK_QUERY_PASSWORD"
+_CLICKSTACK_HTTP_PORT_ENV = "CLICKSTACK_HTTP_PORT"
+_DEFAULT_CLICKSTACK_HTTP_PORT = "8123"
+_CONTAINER_CLICKSTACK_QUERY_URL = f"http://clickstack:{_DEFAULT_CLICKSTACK_HTTP_PORT}"
+
+
+class ClickStackObservabilityBackend(DefaultObservabilityBackend):
+    """Observability backend with OTEL span queries backed by ClickStack."""
+
+    def run_trace_spans(self, run_id: str, limit: int = 500) -> list[TraceSpan]:
+        return self.trace_spans(TraceSpanFilter(run_id=run_id, limit=limit))
+
+    def trace_spans(self, filters: TraceSpanFilter) -> list[TraceSpan]:
+        query_url = self._resolve_clickstack_query_url()
+        query = _build_trace_spans_query(filters)
+        response = requests.post(
+            query_url,
+            data=query.encode("utf-8"),
+            auth=self._resolve_clickstack_query_auth(),
+            timeout=10,
+        )
+        response.raise_for_status()
+        spans: list[TraceSpan] = []
+        for line in response.text.splitlines():
+            if not line.strip():
+                continue
+            spans.append(TraceSpan(**json.loads(line)))
+        return spans
+
+    def _resolve_clickstack_query_url(self) -> str:
+        query_url = os.environ.get(_CLICKSTACK_QUERY_URL_ENV)
+        if query_url:
+            return query_url.rstrip("/")
+        if _running_in_container():
+            return _CONTAINER_CLICKSTACK_QUERY_URL
+        port = os.environ.get(_CLICKSTACK_HTTP_PORT_ENV, _DEFAULT_CLICKSTACK_HTTP_PORT)
+        return f"http://127.0.0.1:{port}"
+
+    def _resolve_clickstack_query_auth(self) -> tuple[str, str] | None:
+        user = os.environ.get(_CLICKSTACK_QUERY_USER_ENV)
+        password = os.environ.get(_CLICKSTACK_QUERY_PASSWORD_ENV)
+        if user is None:
+            return None
+        return (user, password or "")
+
+
+def _build_trace_spans_query(filters: TraceSpanFilter) -> str:
+    where_clauses = _trace_where_clauses(filters)
+    where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""
+    limit = _bounded_limit(filters.limit)
+    return f"""
+SELECT
+    toString(Timestamp) AS timestamp,
+    TraceId AS trace_id,
+    SpanId AS span_id,
+    nullIf(ParentSpanId, '') AS parent_span_id,
+    SpanName AS span_name,
+    ServiceName AS service_name,
+    SpanKind AS span_kind,
+    round(Duration / 1000000, 3) AS duration_ms,
+    StatusCode AS status_code,
+    SpanAttributes AS span_attributes,
+    ResourceAttributes AS resource_attributes
+FROM default.otel_traces
+{where_sql}
+ORDER BY Timestamp ASC
+LIMIT {limit}
+FORMAT JSONEachRow
+""".strip()
+
+
+def _trace_where_clauses(filters: TraceSpanFilter) -> list[str]:
+    clauses: list[str] = []
+    _append_span_attribute_clause(clauses, "phlo.run_id", filters.run_id)
+    _append_span_attribute_clause(clauses, "phlo.asset_key", filters.asset_key)
+    _append_span_attribute_clause(clauses, "phlo.job_name", filters.job_name)
+    _append_exact_clause(clauses, "ServiceName", filters.service_name)
+    _append_exact_clause(clauses, "SpanName", filters.span_name)
+    _append_exact_clause(clauses, "StatusCode", filters.status_code)
+    if filters.start_time:
+        clauses.append(
+            f"Timestamp >= parseDateTimeBestEffort('{_escape_clickhouse_string(filters.start_time)}')"
+        )
+    if filters.end_time:
+        clauses.append(
+            f"Timestamp <= parseDateTimeBestEffort('{_escape_clickhouse_string(filters.end_time)}')"
+        )
+    return clauses
+
+
+def _append_span_attribute_clause(clauses: list[str], key: str, value: str | None) -> None:
+    if value:
+        clauses.append(f"SpanAttributes['{key}'] = '{_escape_clickhouse_string(value)}'")
+
+
+def _append_exact_clause(clauses: list[str], column: str, value: str | None) -> None:
+    if value:
+        clauses.append(f"{column} = '{_escape_clickhouse_string(value)}'")
+
+
+def _bounded_limit(limit: int) -> int:
+    return min(max(limit, 1), 5000)
+
+
+def build_clickstack_observability_spec() -> ObservabilityBackendSpec:
+    """Build the ClickStack observability capability spec."""
+    return ObservabilityBackendSpec(
+        name="default",
+        provider=ClickStackObservabilityBackend(),
+        metadata={
+            "default_stack": ["phlo-otel", "phlo-clickstack"],
+            "service_dependencies": ["clickstack"],
+            "backend": "clickstack",
+        },
+        support=CapabilitySupport(
+            supports_metrics=True,
+            supports_logs=True,
+            supports_dashboards=True,
+            supports_alerts=True,
+        ),
+    )
+
+
+def _escape_clickhouse_string(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("'", "\\'")
+
+
+def _running_in_container() -> bool:
+    return os.path.exists("/.dockerenv")

phlo_clickstack-0.3.0/src/phlo_clickstack/plugin.py

@@ -0,0 +1,44 @@
+"""ClickStack service plugin.
+
+This module defines the ClickStackServicePlugin class which provides
+service registration and definition for the ClickStack observability
+backend service.
+"""
+
+from __future__ import annotations
+
+from phlo.plugins import PackageYamlServicePlugin, PluginMetadata
+
+
+class ClickStackServicePlugin(PackageYamlServicePlugin):
+    """Service plugin for ClickStack.
+
+    Provides ClickStack (ClickHouse-based observability backend) as a
+    managed service within the Phlo services framework. The service
+    definition is loaded from the bundled service.yaml file.
+
+    Example:
+        Plugin is automatically discovered via entry points.
+        Service is started with `phlo services start clickstack`.
+
+    Attributes:
+        service_definition: ClickStack Docker Compose configuration.
+
+    """
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for ClickStack service registration.
+
+        Returns:
+            PluginMetadata: Metadata including name, version, description,
+                author, and tags for discovery.
+
+        """
+        return PluginMetadata(
+            name="clickstack",
+            version="0.1.0",
+            description="ClickStack all-in-one observability backend",
+            author="Phlo Team",
+            tags=["observability", "logs", "metrics", "traces"],
+        )

phlo_clickstack-0.3.0/src/phlo_clickstack/resource_provider.py

@@ -0,0 +1,26 @@
+"""Resource provider for ClickStack observability capabilities."""
+
+from __future__ import annotations
+
+from phlo.plugins import PluginMetadata, ResourceProviderPlugin
+
+from phlo_clickstack.observability_backend import build_clickstack_observability_spec
+
+
+class ClickStackResourceProvider(ResourceProviderPlugin):
+    """Expose ClickStack as the default observability backend capability."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        return PluginMetadata(
+            name="clickstack",
+            version="0.1.0",
+            description="ClickStack observability capability provider",
+            tags=["observability", "logs", "metrics", "traces"],
+        )
+
+    def get_resources(self) -> list:
+        return []
+
+    def get_observability_backends(self):
+        return [build_clickstack_observability_spec()]

{phlo_clickstack-0.2.0 → phlo_clickstack-0.3.0}/src/phlo_clickstack/service.yaml

@@ -9,8 +9,11 @@ image: ${CLICKSTACK_IMAGE:-docker.hyperdx.io/hyperdx/hyperdx-all-in-one}
 compose:
   restart: unless-stopped
   user: "0"
+  environment:
+    FRONTEND_URL: ${CLICKSTACK_PUBLIC_URL:-}
   ports:
     - "${CLICKSTACK_PORT:-8080}:8080"
+    - "${CLICKSTACK_HTTP_PORT:-8123}:8123"
     - "${CLICKSTACK_OTLP_GRPC_PORT:-4317}:4317"
     - "${CLICKSTACK_OTLP_HTTP_PORT:-4318}:4318"
     - "${CLICKSTACK_NATIVE_PORT:-9000}:9000"
@@ -37,6 +40,9 @@ env_vars:
   CLICKSTACK_PORT:
     default: 8080
     description: ClickStack UI port
+  CLICKSTACK_HTTP_PORT:
+    default: 8123
+    description: ClickHouse HTTP query port used by phlo-api trace endpoints
   CLICKSTACK_OTLP_GRPC_PORT:
     default: 4317
     description: ClickStack OTLP gRPC ingest port

{phlo_clickstack-0.2.0 → phlo_clickstack-0.3.0}/src/phlo_clickstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phlo-clickstack
-Version: 0.2.0
+Version: 0.3.0
 Summary: clickstack service plugin for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT

{phlo_clickstack-0.2.0 → phlo_clickstack-0.3.0}/src/phlo_clickstack.egg-info/SOURCES.txt

@@ -1,9 +1,12 @@
 README.md
 pyproject.toml
 src/phlo_clickstack/__init__.py
+src/phlo_clickstack/authorization.py
 src/phlo_clickstack/cli.py
 src/phlo_clickstack/cli_plugin.py
+src/phlo_clickstack/observability_backend.py
 src/phlo_clickstack/plugin.py
+src/phlo_clickstack/resource_provider.py
 src/phlo_clickstack/service.yaml
 src/phlo_clickstack.egg-info/PKG-INFO
 src/phlo_clickstack.egg-info/SOURCES.txt
@@ -11,5 +14,7 @@ src/phlo_clickstack.egg-info/dependency_links.txt
 src/phlo_clickstack.egg-info/entry_points.txt
 src/phlo_clickstack.egg-info/requires.txt
 src/phlo_clickstack.egg-info/top_level.txt
+tests/test_authorization.py
 tests/test_clickstack_cli.py
-tests/test_clickstack_plugin.py
+tests/test_clickstack_plugin.py
+tests/test_observability_backend.py

{phlo_clickstack-0.2.0 → phlo_clickstack-0.3.0}/src/phlo_clickstack.egg-info/entry_points.txt

@@ -1,5 +1,8 @@
 [phlo.plugins.cli]
 clickstack = phlo_clickstack.cli_plugin:ClickStackCliPlugin
 
+[phlo.plugins.resources]
+clickstack = phlo_clickstack.resource_provider:ClickStackResourceProvider
+
 [phlo.plugins.services]
 clickstack = phlo_clickstack.plugin:ClickStackServicePlugin

phlo_clickstack-0.3.0/tests/test_authorization.py

@@ -0,0 +1,188 @@
+"""Tests for ClickStack authorization module."""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+from phlo.cli.authorization import CliPrincipalResolver
+from phlo_clickstack.authorization import (
+    COMMAND_ACTION_MAP,
+    COMMAND_RESOURCE_MAP,
+    MUTATION_COMMANDS,
+    READ_COMMANDS,
+    SURFACE_NAME,
+    ClickStackSurfaceAdapter,
+)
+
+pytestmark = pytest.mark.core_regression
+
+
+class TestClickStackPrincipalResolver:
+    """Tests for the shared CLI principal resolver."""
+
+    def test_resolve_service_account(self):
+        """PHLO_SERVICE_ACCOUNT creates service principal."""
+        env = {"PHLO_SERVICE_ACCOUNT": "ci-bot@phlo.svc"}
+        with patch.dict(os.environ, env, clear=True):
+            resolver = CliPrincipalResolver()
+            principal = resolver.resolve()
+            assert principal.subject == "ci-bot@phlo.svc"
+            assert principal.principal_type == "service"
+            assert "operators" in principal.groups
+
+    def test_resolve_human_principal(self):
+        """PHLO_AUTH_SUBJECT creates human principal."""
+        env = {
+            "PHLO_AUTH_SUBJECT": "user@example.com",
+            "PHLO_AUTH_TYPE": "user",
+            "PHLO_AUTH_GROUPS": "admin,developers",
+        }
+        with patch.dict(os.environ, env, clear=True):
+            resolver = CliPrincipalResolver()
+            principal = resolver.resolve()
+            assert principal.subject == "user@example.com"
+            assert principal.principal_type == "user"
+            assert "admin" in principal.groups
+            assert "developers" in principal.groups
+
+    def test_resolve_human_principal_empty_groups(self):
+        """PHLO_AUTH_SUBJECT with no groups."""
+        env = {
+            "PHLO_AUTH_SUBJECT": "user@example.com",
+            "PHLO_AUTH_TYPE": "user",
+        }
+        with patch.dict(os.environ, env, clear=True):
+            resolver = CliPrincipalResolver()
+            principal = resolver.resolve()
+            assert principal.subject == "user@example.com"
+            assert principal.groups == ()
+
+    def test_resolve_dev_mode_fallback(self):
+        """PHLO_DEV_MODE creates admin fallback with warning."""
+        env = {"PHLO_DEV_MODE": "1"}
+        with patch.dict(os.environ, env, clear=True):
+            resolver = CliPrincipalResolver()
+            principal = resolver.resolve()
+            assert principal.subject == "local:root"
+            assert principal.principal_type == "user"
+            assert "admin" in principal.groups
+
+    def test_resolve_anonymous_default(self):
+        """No env vars creates anonymous principal."""
+        env = {}
+        with patch.dict(os.environ, env, clear=True):
+            resolver = CliPrincipalResolver()
+            principal = resolver.resolve()
+            assert principal.subject == "anonymous"
+            assert principal.principal_type == "user"
+
+
+class TestClickStackSurfaceAdapter:
+    """Tests for ClickStackSurfaceAdapter."""
+
+    def setup_method(self):
+        ClickStackSurfaceAdapter._instance = None
+
+    def teardown_method(self):
+        ClickStackSurfaceAdapter._instance = None
+
+    def test_surface_name(self):
+        adapter = ClickStackSurfaceAdapter()
+        assert adapter.surface_name == SURFACE_NAME
+
+    def test_framework_type(self):
+        adapter = ClickStackSurfaceAdapter()
+        assert adapter.framework_type == "cli"
+
+    def test_list_operations(self):
+        adapter = ClickStackSurfaceAdapter()
+        operations = adapter.list_operations()
+        assert len(operations) == len(MUTATION_COMMANDS)
+        operation_names = {op["operation_name"] for op in operations}
+        for cmd in MUTATION_COMMANDS:
+            assert cmd in operation_names
+
+    def test_list_operations_has_required_fields(self):
+        adapter = ClickStackSurfaceAdapter()
+        for op in adapter.list_operations():
+            assert "action" in op
+            assert "resource_type" in op
+            assert "operation_name" in op
+
+    def test_is_active(self):
+        adapter = ClickStackSurfaceAdapter()
+        assert adapter.is_active(None) is True
+
+    def test_get_instance_singleton(self):
+        adapter1 = ClickStackSurfaceAdapter.get_instance()
+        adapter2 = ClickStackSurfaceAdapter.get_instance()
+        assert adapter1 is adapter2
+
+    def test_command_mapped_correctly(self):
+        """All mutation commands have resource and action mappings."""
+        for cmd in MUTATION_COMMANDS:
+            assert cmd in COMMAND_RESOURCE_MAP, f"Missing resource mapping for {cmd}"
+            assert cmd in COMMAND_ACTION_MAP, f"Missing action mapping for {cmd}"
+
+
+class TestEnforcement:
+    """Tests for ClickStack mutation enforcement."""
+
+    def setup_method(self):
+        ClickStackSurfaceAdapter._instance = None
+
+    def teardown_method(self):
+        ClickStackSurfaceAdapter._instance = None
+
+    def test_check_read_command_allowed(self):
+        """Read commands are always allowed."""
+        adapter = ClickStackSurfaceAdapter()
+        for cmd in READ_COMMANDS:
+            result = adapter.check_command_authorization(cmd)
+            assert result.allowed, f"Read command {cmd} should be allowed"
+
+    def test_check_unknown_command_denied(self):
+        """Unknown commands are denied."""
+        adapter = ClickStackSurfaceAdapter()
+        result = adapter.check_command_authorization("unknown.command")
+        assert not result.allowed
+        assert result.reason_code == "unknown_command"
+
+
+class TestMutationCommandLists:
+    """Tests for command classification lists."""
+
+    def test_no_overlap_between_read_and_mutation(self):
+        """Read and mutation command sets are disjoint."""
+        overlap = READ_COMMANDS & MUTATION_COMMANDS
+        assert overlap == set(), f"Commands in both sets: {overlap}"
+
+    def test_all_clickstack_commands_covered(self):
+        """All clickstack subcommands are classified."""
+        all_clickstack = {"clickstack.query"}
+        classified = READ_COMMANDS | MUTATION_COMMANDS
+        unclassified = all_clickstack - classified
+        assert unclassified == set(), f"Unclassified clickstack commands: {unclassified}"
+
+
+class TestResourceActionMapping:
+    """Tests for command to resource/action mapping."""
+
+    def test_query_command_resource_mapping(self):
+        """clickstack.query maps to dataset resource."""
+        assert COMMAND_RESOURCE_MAP["clickstack.query"] == "dataset"
+
+    def test_query_command_action_mapping(self):
+        """clickstack.query maps to dataset.write action."""
+        assert COMMAND_ACTION_MAP["clickstack.query"] == "dataset.write"
+
+    def test_action_format(self):
+        """All actions follow resource.action pattern."""
+        for cmd, action in COMMAND_ACTION_MAP.items():
+            parts = action.split(".")
+            assert len(parts) >= 2, (
+                f"Action {action} for {cmd} should have at least resource.action"
+            )

{phlo_clickstack-0.2.0 → phlo_clickstack-0.3.0}/tests/test_clickstack_cli.py

@@ -37,8 +37,8 @@ def test_clickstack_query_runs_clickhouse_client(monkeypatch) -> None:
         return CompletedProcess(cmd, 0, stdout='{"1":1}\n', stderr="")
 
     monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr("phlo_clickstack.cli._require_container_backend", lambda: None)
     monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
-    monkeypatch.setattr("phlo_clickstack.cli.which", lambda _name: "/usr/bin/docker")
     monkeypatch.setattr(
         "phlo_clickstack.cli.compose_base_cmd",
         lambda **_kwargs: ["docker", "compose", "-p", "demo"],
@@ -51,6 +51,60 @@ def test_clickstack_query_runs_clickhouse_client(monkeypatch) -> None:
     assert result.output == '{"1":1}\n'
 
 
+def test_clickstack_query_uses_selected_container_backend(monkeypatch, tmp_path) -> None:
+    phlo_dir = tmp_path / ".phlo"
+    phlo_dir.mkdir()
+    (phlo_dir / "docker-compose.yml").write_text("services:\n  clickstack: {}\n")
+    (phlo_dir / ".env").write_text("")
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("PHLO_CONTAINER_BACKEND", "podman")
+    monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
+
+    calls: list[list[str]] = []
+    monkeypatch.setattr(
+        "phlo.cli.commands.services.utils.require_container_backend",
+        lambda *_args, **_kwargs: None,
+    )
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.run_command",
+        lambda cmd, **_kwargs: calls.append(cmd) or CompletedProcess(cmd, 0, stdout="", stderr=""),
+    )
+
+    result = CliRunner().invoke(clickstack_group, ["query", "SELECT 1"])
+
+    assert result.exit_code == 0, result.output
+    assert calls
+    assert calls[0][:2] == ["podman", "compose"]
+
+
+def test_clickstack_query_uses_project_container_backend_config(monkeypatch, tmp_path) -> None:
+    phlo_dir = tmp_path / ".phlo"
+    phlo_dir.mkdir()
+    (phlo_dir / "docker-compose.yml").write_text("services:\n  clickstack: {}\n")
+    (phlo_dir / ".env").write_text("")
+    (tmp_path / "phlo.yaml").write_text(
+        "name: demo\ninfrastructure:\n  container_backend: podman\n"
+    )
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("PHLO_CONTAINER_BACKEND", raising=False)
+    monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
+    monkeypatch.setattr(
+        "phlo.cli.commands.services.utils.require_container_backend",
+        lambda *_args, **_kwargs: None,
+    )
+
+    calls: list[list[str]] = []
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.run_command",
+        lambda cmd, **_kwargs: calls.append(cmd) or CompletedProcess(cmd, 0, stdout="", stderr=""),
+    )
+
+    result = CliRunner().invoke(clickstack_group, ["query", "SELECT 1"])
+
+    assert result.exit_code == 0, result.output
+    assert calls[0][:2] == ["podman", "compose"]
+
+
 def test_clickstack_query_supports_file(monkeypatch, tmp_path) -> None:
     """Query command should read SQL from a file."""
     sql_file = tmp_path / "query.sql"
@@ -63,8 +117,8 @@ def test_clickstack_query_supports_file(monkeypatch, tmp_path) -> None:
         return CompletedProcess(cmd, 0, stdout="42\n", stderr="")
 
     monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr("phlo_clickstack.cli._require_container_backend", lambda: None)
     monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
-    monkeypatch.setattr("phlo_clickstack.cli.which", lambda _name: "/usr/bin/docker")
     monkeypatch.setattr(
         "phlo_clickstack.cli.compose_base_cmd",
         lambda **_kwargs: ["docker", "compose", "-p", "demo"],
@@ -80,8 +134,8 @@ def test_clickstack_query_supports_file(monkeypatch, tmp_path) -> None:
 def test_clickstack_query_rejects_missing_input(monkeypatch) -> None:
     """Query command should fail clearly when no SQL is provided."""
     monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr("phlo_clickstack.cli._require_container_backend", lambda: None)
     monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
-    monkeypatch.setattr("phlo_clickstack.cli.which", lambda _name: "/usr/bin/docker")
     monkeypatch.setattr(
         "phlo_clickstack.cli.run_command",
         lambda cmd, **_kwargs: (
@@ -106,8 +160,8 @@ def test_clickstack_query_surfaces_timeout(monkeypatch) -> None:
         raise TimeoutExpired(cmd=cmd, timeout=30)
 
     monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr("phlo_clickstack.cli._require_container_backend", lambda: None)
     monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
-    monkeypatch.setattr("phlo_clickstack.cli.which", lambda _name: "/usr/bin/docker")
     monkeypatch.setattr(
         "phlo_clickstack.cli.compose_base_cmd",
         lambda **_kwargs: ["docker", "compose", "-p", "demo"],

phlo_clickstack-0.3.0/tests/test_observability_backend.py

@@ -0,0 +1,100 @@
+"""Tests for ClickStack observability backend capability."""
+
+from __future__ import annotations
+
+from phlo_clickstack.observability_backend import (
+    ClickStackObservabilityBackend,
+    _build_trace_spans_query,
+    build_clickstack_observability_spec,
+)
+from phlo.capabilities import TraceSpanFilter
+
+
+class _FakeResponse:
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+    def raise_for_status(self) -> None:
+        return None
+
+
+def test_build_clickstack_observability_spec_uses_default_name() -> None:
+    spec = build_clickstack_observability_spec()
+
+    assert spec.name == "default"
+    assert spec.metadata["backend"] == "clickstack"
+    assert spec.support.supports_logs is True
+
+
+def test_clickstack_backend_defaults_to_host_http_port(monkeypatch) -> None:
+    monkeypatch.delenv("CLICKSTACK_QUERY_URL", raising=False)
+    monkeypatch.delenv("CLICKSTACK_HTTP_PORT", raising=False)
+    monkeypatch.setattr(
+        "phlo_clickstack.observability_backend._running_in_container", lambda: False
+    )
+
+    backend = ClickStackObservabilityBackend()
+
+    assert backend._resolve_clickstack_query_url() == "http://127.0.0.1:8123"
+
+
+def test_clickstack_backend_uses_container_url_in_container(monkeypatch) -> None:
+    monkeypatch.delenv("CLICKSTACK_QUERY_URL", raising=False)
+    monkeypatch.setattr("phlo_clickstack.observability_backend._running_in_container", lambda: True)
+
+    backend = ClickStackObservabilityBackend()
+
+    assert backend._resolve_clickstack_query_url() == "http://clickstack:8123"
+
+
+def test_clickstack_backend_queries_trace_spans(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_post(url: str, data: bytes, auth: tuple[str, str] | None, timeout: int):  # noqa: ANN001
+        captured["url"] = url
+        captured["query"] = data.decode("utf-8")
+        captured["auth"] = auth
+        return _FakeResponse(
+            '{"timestamp":"2026-01-01T00:00:00Z","trace_id":"abc123","span_id":"span-1","parent_span_id":null,"span_name":"materialize_orders","service_name":"dagster","span_kind":"INTERNAL","duration_ms":12.5,"status_code":"STATUS_CODE_OK","span_attributes":{"phlo.run_id":"run-123"},"resource_attributes":{"service.name":"dagster"}}\n'
+        )
+
+    monkeypatch.setattr("phlo_clickstack.observability_backend.requests.post", fake_post)
+    monkeypatch.setenv("CLICKSTACK_QUERY_URL", "http://clickstack.test:8123")
+    monkeypatch.setenv("CLICKSTACK_QUERY_USER", "api")
+    monkeypatch.setenv("CLICKSTACK_QUERY_PASSWORD", "api")
+
+    backend = ClickStackObservabilityBackend()
+    spans = backend.run_trace_spans("run-123", limit=25)
+
+    assert captured["url"] == "http://clickstack.test:8123"
+    assert "otel_traces" in captured["query"]
+    assert "run-123" in captured["query"]
+    assert "LIMIT 25" in captured["query"]
+    assert captured["auth"] == ("api", "api")
+    assert spans[0].trace_id == "abc123"
+
+
+def test_build_trace_spans_query_includes_filters() -> None:
+    query = _build_trace_spans_query(
+        TraceSpanFilter(
+            run_id="run-123",
+            asset_key="silver/orders",
+            job_name="daily_orders",
+            service_name="dagster",
+            span_name="materialize_orders",
+            status_code="STATUS_CODE_ERROR",
+            start_time="2026-04-26T00:00:00Z",
+            end_time="2026-04-26T01:00:00Z",
+            limit=25,
+        )
+    )
+
+    assert "SpanAttributes['phlo.run_id'] = 'run-123'" in query
+    assert "SpanAttributes['phlo.asset_key'] = 'silver/orders'" in query
+    assert "SpanAttributes['phlo.job_name'] = 'daily_orders'" in query
+    assert "ServiceName = 'dagster'" in query
+    assert "SpanName = 'materialize_orders'" in query
+    assert "StatusCode = 'STATUS_CODE_ERROR'" in query
+    assert "Timestamp >= parseDateTimeBestEffort('2026-04-26T00:00:00Z')" in query
+    assert "Timestamp <= parseDateTimeBestEffort('2026-04-26T01:00:00Z')" in query
+    assert "LIMIT 25" in query

phlo_clickstack-0.2.0/src/phlo_clickstack/__init__.py

@@ -1 +0,0 @@
-"""ClickStack service package for Phlo."""

phlo_clickstack-0.2.0/src/phlo_clickstack/cli_plugin.py

@@ -1,26 +0,0 @@
-"""CLI plugin for ClickStack commands."""
-
-from __future__ import annotations
-
-import click
-
-from phlo.plugins.base import CliCommandPlugin, PluginMetadata
-
-from phlo_clickstack.cli import clickstack_group
-
-
-class ClickStackCliPlugin(CliCommandPlugin):
-    """Register ClickStack CLI commands."""
-
-    @property
-    def metadata(self) -> PluginMetadata:
-        """Return plugin metadata for ClickStack CLI registration."""
-        return PluginMetadata(
-            name="clickstack",
-            version="0.1.0",
-            description="CLI commands for ClickStack query access",
-        )
-
-    def get_cli_commands(self) -> list[click.Command]:
-        """Return ClickStack CLI commands."""
-        return [clickstack_group]

phlo_clickstack-0.2.0/src/phlo_clickstack/plugin.py

@@ -1,31 +0,0 @@
-"""ClickStack service plugin."""
-
-from __future__ import annotations
-
-from importlib import resources
-from typing import Any
-
-import yaml
-
-from phlo.plugins import PluginMetadata, ServicePlugin
-
-
-class ClickStackServicePlugin(ServicePlugin):
-    """Service plugin for ClickStack."""
-
-    @property
-    def metadata(self) -> PluginMetadata:
-        """Return plugin metadata for ClickStack service registration."""
-        return PluginMetadata(
-            name="clickstack",
-            version="0.1.0",
-            description="ClickStack all-in-one observability backend",
-            author="Phlo Team",
-            tags=["observability", "logs", "metrics", "traces"],
-        )
-
-    @property
-    def service_definition(self) -> dict[str, Any]:
-        """Load and return the ClickStack service definition."""
-        service_path = resources.files("phlo_clickstack").joinpath("service.yaml")
-        return yaml.safe_load(service_path.read_text(encoding="utf-8"))