phlo-clickstack 0.4.0__tar.gz → 0.15.1__tar.gz

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: phlo-clickstack
-Version: 0.4.0
+Version: 0.15.1
 Summary: clickstack service plugin for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT
 Requires-Python: >=3.11
 Description-Content-Type: text/plain
-Requires-Dist: phlo>=0.1.0
+Requires-Dist: phlo<0.16,>=0.15.1
 Requires-Dist: requests>=2.32.5
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/pyproject.toml

@@ -7,13 +7,13 @@ requires = [
 
 [project]
 dependencies = [
-    "phlo>=0.1.0",
+    "phlo>=0.15.1,<0.16",
     "requests>=2.32.5",
 ]
 description = "clickstack service plugin for Phlo"
 name = "phlo-clickstack"
 requires-python = ">=3.11"
-version = "0.4.0"
+version = "0.15.1"
 
 [[project.authors]]
 email = "team@phlo.dev"

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/src/phlo_clickstack/authorization.py

@@ -1,8 +1,12 @@
-"""phlo_clickstack CLI authorization table."""
+"""Authorization table for the phlo-clickstack CLI surface.
+
+Declares which commands mutate state and maps every command onto the resource
+and action names evaluated by the shared CLI surface adapter.
+"""
 
 from __future__ import annotations
 
-from phlo.cli.authorization import cli_surface_adapter_class
+from phlo.cli.authorization import CliSurfaceAdapter, cli_surface_adapter_class
 
 SURFACE_NAME = "phlo-clickstack"
 FRAMEWORK_TYPE = "cli"
@@ -23,5 +27,6 @@ ClickStackSurfaceAdapter = cli_surface_adapter_class(
 )
 
 
-def get_adapter() -> ClickStackSurfaceAdapter:
+def get_adapter() -> CliSurfaceAdapter:
+    """Return the shared ClickStackSurfaceAdapter instance for this surface."""
     return ClickStackSurfaceAdapter.get_instance()

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/src/phlo_clickstack/cli.py

@@ -35,23 +35,10 @@ logger = get_logger(__name__)
 def _read_query(*, query: str | None, file: Path | None) -> str:
     """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.
-
+    Accepts either an inline SQL query string or a path to a SQL file;
+    exactly one non-empty source must be provided. Raises ClickException
+    when both are given, the file is unreadable/empty, or neither is
+    provided.
     """
     if query and file:
         raise exclusive_options_error("an inline query", "--file")
@@ -71,15 +58,8 @@ def _read_query(*, query: str | None, file: Path | None) -> str:
 def _ensure_phlo_dir() -> Path:
     """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.
-
+    Required for Docker Compose project configuration; raises
+    ClickException when the directory does not exist.
     """
     return ensure_compose_project()
 
@@ -113,22 +93,9 @@ def clickstack_query(
 
     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.
-
+    and a running phlo services stack with ClickStack enabled; raises
+    ClickException when Docker is unavailable, the .phlo directory is
+    missing, inputs are invalid, execution fails, or the query times out.
     """
     sql = _read_query(query=query, file=query_file)
     if is_mutating_sql(sql):

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/src/phlo_clickstack/cli_plugin.py

@@ -1,4 +1,10 @@
-"""Clickstack CLI plugin registration."""
+"""Clickstack CLI plugin registration.
+
+Registers the clickstack command group with the plugin system via
+cli_command_plugin_class; owns no logic beyond registration.
+
+Loaded through the phlo plugin entry-point mechanism at startup rather than imported directly.
+"""
 
 from __future__ import annotations
 

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/src/phlo_clickstack/observability_backend.py

@@ -1,4 +1,10 @@
-"""ClickStack-backed observability capability provider."""
+"""ClickStack-backed observability capability provider.
+
+Span queries post SQL to ClickStack's HTTP endpoint and decode its
+newline-delimited JSON reply into TraceSpans. The endpoint resolves from
+CLICKSTACK_QUERY_URL, falling back to the in-container service address or
+localhost depending on environment.
+"""
 
 from __future__ import annotations
 
@@ -27,9 +33,14 @@ 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 trace spans for a single run id, bounded by limit."""
         return self.trace_spans(TraceSpanFilter(run_id=run_id, limit=limit))
 
     def trace_spans(self, filters: TraceSpanFilter) -> list[TraceSpan]:
+        """Post the span query to ClickStack and decode newline-delimited JSON into TraceSpans.
+
+        Raises requests.HTTPError when the query request fails.
+        """
         query_url = self._resolve_clickstack_query_url()
         query = _build_trace_spans_query(filters)
         response = requests.post(

phlo_clickstack-0.15.1/src/phlo_clickstack/plugin.py

@@ -0,0 +1,23 @@
+"""Clickstack service plugin registration.
+
+Declares the ClickStack observability backend (logs, metrics, traces)
+as a service plugin. The class object is created at import time via
+service_plugin_class so plugin discovery can pick it up without
+instantiation.
+Loaded through the phlo plugin entry-point mechanism at startup rather than imported directly.
+Registers the clickstack observability backend service through phlo.plugins.
+"""
+
+from __future__ import annotations
+
+from phlo.plugins import service_plugin_class
+
+
+ClickStackServicePlugin = service_plugin_class(
+    "ClickStackServicePlugin",
+    name="clickstack",
+    version="0.1.0",
+    description="ClickStack all-in-one observability backend",
+    author="Phlo Team",
+    tags=["observability", "logs", "metrics", "traces"],
+)

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/src/phlo_clickstack/resource_provider.py

@@ -1,4 +1,10 @@
-"""Resource provider for ClickStack observability capabilities."""
+"""Resource provider for ClickStack observability capabilities.
+
+ClickStackResourceProvider registers under the "clickstack" name and reports
+ClickStack as an observability backend; it declares no standalone resources.
+Loaded through the phlo plugin entry-point mechanism at startup rather than
+imported directly; declares ClickStack as an observability backend via phlo.plugins.
+"""
 
 from __future__ import annotations
 
@@ -12,6 +18,7 @@ class ClickStackResourceProvider(ResourceProviderPlugin):
 
     @property
     def metadata(self) -> PluginMetadata:
+        """Return the ClickStack provider metadata."""
         return PluginMetadata(
             name="clickstack",
             version="0.1.0",
@@ -20,7 +27,9 @@ class ClickStackResourceProvider(ResourceProviderPlugin):
         )
 
     def get_resources(self) -> list:
+        """Report no standalone resources."""
         return []
 
     def get_observability_backends(self):
+        """Return the ClickStack observability backend spec."""
         return [build_clickstack_observability_spec()]

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/src/phlo_clickstack/service.yaml

@@ -4,7 +4,7 @@ category: observability
 default: false
 profile: observability
 
-image: ${CLICKSTACK_IMAGE:-docker.hyperdx.io/hyperdx/hyperdx-all-in-one}
+image: docker.io/hyperdx/hyperdx-all-in-one:2.31.0@sha256:b01cc48cb5aaf30d630865a88217c826ab86fb9828374201f6cd7c539d5beed1
 
 compose:
   restart: unless-stopped
@@ -32,9 +32,6 @@ compose:
     retries: 10
 
 env_vars:
-  CLICKSTACK_IMAGE:
-    default: "docker.hyperdx.io/hyperdx/hyperdx-all-in-one"
-    description: Official ClickStack all-in-one image reference
   CLICKSTACK_PORT:
     default: 18080
     description: ClickStack UI port

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/src/phlo_clickstack.egg-info/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: phlo-clickstack
-Version: 0.4.0
+Version: 0.15.1
 Summary: clickstack service plugin for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT
 Requires-Python: >=3.11
 Description-Content-Type: text/plain
-Requires-Dist: phlo>=0.1.0
+Requires-Dist: phlo<0.16,>=0.15.1
 Requires-Dist: requests>=2.32.5
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/src/phlo_clickstack.egg-info/requires.txt

@@ -1,4 +1,4 @@
-phlo>=0.1.0
+phlo<0.16,>=0.15.1
 requests>=2.32.5
 
 [dev]

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/tests/test_authorization.py

@@ -1,4 +1,10 @@
-"""Tests for ClickStack authorization module."""
+"""Tests for ClickStack authorization module.
+
+Package-specific command-table coverage plus the shared surface-adapter
+contract from ``phlo_testing.authorization_surface``: reads skip enforcement,
+unknown commands deny closed, mutation commands honor policy allow/deny, and
+the shared ``CliPrincipalResolver`` environment fallbacks hold.
+"""
 
 from __future__ import annotations
 
@@ -8,6 +14,13 @@ from unittest.mock import patch
 import pytest
 
 from phlo.cli.authorization import CliPrincipalResolver
+from phlo_testing.authorization_surface import (
+    assert_mutation_enforcement_allows_and_denies,
+    assert_read_commands_allow_without_enforcement,
+    assert_unknown_command_denied,
+    reset_surface_adapter_singleton,
+    run_cli_principal_resolver_contract,
+)
 from phlo_clickstack.authorization import (
     COMMAND_ACTION_MAP,
     COMMAND_RESOURCE_MAP,
@@ -21,32 +34,7 @@ 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
+    """Extra principal-resolver edge case beyond the shared contract."""
 
     def test_resolve_human_principal_empty_groups(self):
         """PHLO_AUTH_SUBJECT with no groups."""
@@ -60,34 +48,19 @@ class TestClickStackPrincipalResolver:
             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"
+def test_cli_principal_resolver_contract():
+    """The shared CLI principal resolver environment fallbacks hold."""
+    run_cli_principal_resolver_contract()
 
 
 class TestClickStackSurfaceAdapter:
     """Tests for ClickStackSurfaceAdapter."""
 
-    def setup_method(self):
-        ClickStackSurfaceAdapter._instance = None
-
-    def teardown_method(self):
-        ClickStackSurfaceAdapter._instance = None
+    @pytest.fixture(autouse=True)
+    def reset_singleton(self):
+        with reset_surface_adapter_singleton(ClickStackSurfaceAdapter):
+            yield
 
     def test_surface_name(self):
         adapter = ClickStackSurfaceAdapter()
@@ -131,25 +104,24 @@ class TestClickStackSurfaceAdapter:
 class TestEnforcement:
     """Tests for ClickStack mutation enforcement."""
 
-    def setup_method(self):
-        ClickStackSurfaceAdapter._instance = None
+    @pytest.fixture(autouse=True)
+    def reset_singleton(self):
+        with reset_surface_adapter_singleton(ClickStackSurfaceAdapter):
+            yield
 
-    def teardown_method(self):
-        ClickStackSurfaceAdapter._instance = None
+    def test_read_commands_allow_without_enforcement(self):
+        """Read commands allow without touching the enforcement path."""
+        assert_read_commands_allow_without_enforcement(ClickStackSurfaceAdapter())
 
-    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_unknown_command_denied_closed(self):
+        """Unknown commands are denied closed."""
+        assert_unknown_command_denied(ClickStackSurfaceAdapter(), "clickstack.unknown")
 
-    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"
+    def test_clickstack_query_mutation_honors_policy_decision(self):
+        """clickstack.query flows a policy allow through and blocks a policy deny."""
+        assert_mutation_enforcement_allows_and_denies(
+            ClickStackSurfaceAdapter(), "clickstack.query"
+        )
 
 
 class TestMutationCommandLists:

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/tests/test_clickstack_cli.py

@@ -1,4 +1,11 @@
-"""Tests for ClickStack CLI commands."""
+"""Tests for ClickStack CLI commands.
+
+Drives the query command through CliRunner with mocked subprocess calls to
+verify SQL executes inside the ClickStack container via the project's
+configured compose backend, that mutating statements pass through surface
+mutation authorization, and that missing input or timeouts surface as CLI
+errors.
+"""
 
 from __future__ import annotations
 

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/tests/test_clickstack_plugin.py

@@ -1,4 +1,8 @@
-"""Tests for ClickStack service plugin."""
+"""Tests for the ClickStack service plugin.
+
+Covers service definition metadata, pinned upstream images, and CLI rejection
+of commands without an initialized .phlo directory.
+"""
 
 from click.testing import CliRunner
 
@@ -21,6 +25,17 @@ def test_clickstack_service_definition() -> None:
     assert "./volumes/clickstack:/var/lib/clickhouse" not in defn["compose"]["volumes"]
 
 
+def test_clickstack_uses_pinned_upstream_image() -> None:
+    definition = ClickStackServicePlugin().service_definition
+
+    assert definition["image"] == (
+        "docker.io/hyperdx/hyperdx-all-in-one:2.31.0@"
+        "sha256:b01cc48cb5aaf30d630865a88217c826ab86fb9828374201f6cd7c539d5beed1"
+    )
+    assert "build" not in definition
+    assert "CLICKSTACK_IMAGE" not in definition["env_vars"]
+
+
 def test_clickstack_plugin_metadata() -> None:
     """Validate ClickStack plugin metadata."""
     plugin = ClickStackServicePlugin()

{phlo_clickstack-0.4.0 → phlo_clickstack-0.15.1}/tests/test_observability_backend.py

@@ -1,4 +1,9 @@
-"""Tests for ClickStack observability backend capability."""
+"""Tests for ClickStack observability backend capability.
+
+Covers spec defaults, host-port versus in-container query URL selection,
+trace span queries issued to the ClickStack HTTP API, and filter-aware query
+construction.
+"""
 
 from __future__ import annotations
 

phlo_clickstack-0.4.0/src/phlo_clickstack/plugin.py

@@ -1,15 +0,0 @@
-"""Clickstack service plugin registration."""
-
-from __future__ import annotations
-
-from phlo.plugins import service_plugin_class
-
-
-ClickStackServicePlugin = service_plugin_class(
-    "ClickStackServicePlugin",
-    name="clickstack",
-    version="0.1.0",
-    description="ClickStack all-in-one observability backend",
-    author="Phlo Team",
-    tags=["observability", "logs", "metrics", "traces"],
-)