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

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: phlo-clickstack
-Version: 0.3.0
+Version: 0.4.0
 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: pyyaml>=6.0.1
+Requires-Dist: requests>=2.32.5
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"

{phlo_clickstack-0.3.0 → phlo_clickstack-0.4.0}/README.md

@@ -5,8 +5,7 @@ ClickStack observability service for Phlo.
 ## Overview
 
 `phlo-clickstack` packages the official ClickStack all-in-one image so Phlo can
-ship a single OpenTelemetry-native observability target with logs, metrics, and
-traces in one UI.
+query ClickHouse-backed observability data and link to the HyperDX UI.
 
 ## Installation
 
@@ -27,11 +26,6 @@ phlo services start --service clickstack
 phlo clickstack query "SELECT count() FROM default.otel_logs"
 ```
 
-Point `phlo-otel` at ClickStack:
-
-```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-export OTEL_TRACES_EXPORTER=otlp
-export OTEL_METRICS_EXPORTER=otlp
-export OTEL_LOGS_EXPORTER=otlp
-```
+The bundled all-in-one image exposes the HyperDX UI and ClickHouse query ports.
+Use Alloy or another collector for OTLP ingest; this service does not publish
+OTLP ports by default because the image does not listen on those ports.

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

@@ -8,12 +8,12 @@ requires = [
 [project]
 dependencies = [
     "phlo>=0.1.0",
-    "pyyaml>=6.0.1",
+    "requests>=2.32.5",
 ]
 description = "clickstack service plugin for Phlo"
 name = "phlo-clickstack"
 requires-python = ">=3.11"
-version = "0.3.0"
+version = "0.4.0"
 
 [[project.authors]]
 email = "team@phlo.dev"

phlo_clickstack-0.4.0/src/phlo_clickstack/authorization.py

@@ -0,0 +1,27 @@
+"""phlo_clickstack CLI authorization table."""
+
+from __future__ import annotations
+
+from phlo.cli.authorization import cli_surface_adapter_class
+
+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"}
+
+ClickStackSurfaceAdapter = cli_surface_adapter_class(
+    "ClickStackSurfaceAdapter",
+    surface_name=SURFACE_NAME,
+    mutation_commands=MUTATION_COMMANDS,
+    read_commands=READ_COMMANDS,
+    command_resource_map=COMMAND_RESOURCE_MAP,
+    command_action_map=COMMAND_ACTION_MAP,
+    default_action_prefix="clickstack",
+    default_resource_prefix="clickstack",
+)
+
+
+def get_adapter() -> ClickStackSurfaceAdapter:
+    return ClickStackSurfaceAdapter.get_instance()

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

@@ -13,11 +13,21 @@ from subprocess import TimeoutExpired
 
 import click
 
+from phlo.cli.authorization_wrappers import enforce_surface_mutation_authorization
 from phlo.cli.commands.services import utils as services_utils
+from phlo.cli.commands.services.utils import ensure_compose_project
 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
+from phlo.cli.output import (
+    empty_file_error,
+    exclusive_options_error,
+    file_read_error,
+    missing_query_error,
+)
+from phlo.cli.sql import is_mutating_sql
 from phlo.logging import get_logger
+from phlo_clickstack.authorization import get_adapter as get_clickstack_adapter
 
 logger = get_logger(__name__)
 
@@ -44,18 +54,18 @@ def _read_query(*, query: str | None, file: Path | None) -> str:
 
     """
     if query and file:
-        raise click.ClickException("Use either an inline query or --file, not both.")
+        raise exclusive_options_error("an inline query", "--file")
     if file is not None:
         try:
             sql = file.read_text(encoding="utf-8")
         except OSError as exc:
-            raise click.ClickException(f"Failed to read SQL file: {file}") from exc
+            raise file_read_error(file) from exc
         if sql.strip():
             return sql
-        raise click.ClickException(f"SQL file is empty: {file}")
+        raise empty_file_error(file)
     if query and query.strip():
         return query
-    raise click.ClickException("Provide a SQL query argument or --file.")
+    raise missing_query_error(command_hint='phlo clickstack query "SELECT 1"')
 
 
 def _ensure_phlo_dir() -> Path:
@@ -71,10 +81,7 @@ def _ensure_phlo_dir() -> Path:
         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.")
+    return ensure_compose_project()
 
 
 def _require_container_backend() -> None:
@@ -123,10 +130,12 @@ def clickstack_query(
         click.ClickException: If query times out.
 
     """
+    sql = _read_query(query=query, file=query_file)
+    if is_mutating_sql(sql):
+        enforce_surface_mutation_authorization("clickstack.query", get_clickstack_adapter)
     _require_container_backend()
     phlo_dir = _ensure_phlo_dir()
     project_name = get_project_name()
-    sql = _read_query(query=query, file=query_file)
 
     cmd = compose_base_cmd(phlo_dir=phlo_dir, project_name=project_name)
     cmd.extend(

phlo_clickstack-0.4.0/src/phlo_clickstack/cli_plugin.py

@@ -0,0 +1,17 @@
+"""Clickstack CLI plugin registration."""
+
+from __future__ import annotations
+
+
+from phlo.plugins.base import cli_command_plugin_class
+
+from phlo_clickstack.cli import clickstack_group
+
+
+ClickStackCliPlugin = cli_command_plugin_class(
+    "ClickStackCliPlugin",
+    name="clickstack",
+    version="0.1.0",
+    description="CLI commands for ClickStack query access",
+    commands=[clickstack_group],
+)

phlo_clickstack-0.4.0/src/phlo_clickstack/plugin.py

@@ -0,0 +1,15 @@
+"""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"],
+)

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

@@ -12,13 +12,11 @@ compose:
   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"
+    - "${CLICKSTACK_PORT:-18080}:8080"
+    - "${CLICKSTACK_HTTP_PORT:-18123}:8123"
+    - "${CLICKSTACK_NATIVE_PORT:-19002}:9000"
   volumes:
-    - ./volumes/clickstack:/var/lib/clickhouse
+    - clickstack-data:/var/lib/clickhouse
   healthcheck:
     test:
       [
@@ -38,19 +36,13 @@ env_vars:
     default: "docker.hyperdx.io/hyperdx/hyperdx-all-in-one"
     description: Official ClickStack all-in-one image reference
   CLICKSTACK_PORT:
-    default: 8080
+    default: 18080
     description: ClickStack UI port
   CLICKSTACK_HTTP_PORT:
-    default: 8123
+    default: 18123
     description: ClickHouse HTTP query port used by phlo-api trace endpoints
-  CLICKSTACK_OTLP_GRPC_PORT:
-    default: 4317
-    description: ClickStack OTLP gRPC ingest port
-  CLICKSTACK_OTLP_HTTP_PORT:
-    default: 4318
-    description: ClickStack OTLP HTTP ingest port
   CLICKSTACK_NATIVE_PORT:
-    default: 9000
+    default: 19002
     description: ClickHouse native port exposed by the all-in-one image
   CLICKSTACK_PUBLIC_URL:
     default: ""

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: phlo-clickstack
-Version: 0.3.0
+Version: 0.4.0
 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: pyyaml>=6.0.1
+Requires-Dist: requests>=2.32.5
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"

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

@@ -1,5 +1,5 @@
 phlo>=0.1.0
-pyyaml>=6.0.1
+requests>=2.32.5
 
 [dev]
 pytest>=7.0

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

@@ -51,6 +51,36 @@ def test_clickstack_query_runs_clickhouse_client(monkeypatch) -> None:
     assert result.output == '{"1":1}\n'
 
 
+def test_clickstack_query_authorizes_only_mutating_sql(monkeypatch) -> None:
+    calls: list[str] = []
+
+    monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr(
+        "phlo_clickstack.cli._require_container_backend",
+        lambda: calls.append("backend"),
+    )
+    monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.compose_base_cmd",
+        lambda **_kwargs: ["docker", "compose", "-p", "demo"],
+    )
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.run_command",
+        lambda cmd, **_kwargs: CompletedProcess(cmd, 0, stdout="ok\n", stderr=""),
+    )
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.enforce_surface_mutation_authorization",
+        lambda *_args, **_kwargs: calls.append("auth"),
+    )
+
+    select_result = CliRunner().invoke(clickstack_group, ["query", "SELECT 1"])
+    insert_result = CliRunner().invoke(clickstack_group, ["query", "INSERT INTO t VALUES (1)"])
+
+    assert select_result.exit_code == 0
+    assert insert_result.exit_code == 0
+    assert calls == ["backend", "auth", "backend"]
+
+
 def test_clickstack_query_uses_selected_container_backend(monkeypatch, tmp_path) -> None:
     phlo_dir = tmp_path / ".phlo"
     phlo_dir.mkdir()
@@ -148,7 +178,9 @@ def test_clickstack_query_rejects_missing_input(monkeypatch) -> None:
     result = CliRunner().invoke(clickstack_group, ["query"])
 
     assert result.exit_code != 0
-    assert "Provide a SQL query argument or --file." in result.output
+    assert "Error: no SQL query provided" in result.output
+    assert "Provide an inline query argument or pass --file." in result.output
+    assert 'Run: phlo clickstack query "SELECT 1"' in result.output
 
 
 def test_clickstack_query_surfaces_timeout(monkeypatch) -> None:

phlo_clickstack-0.4.0/tests/test_clickstack_plugin.py

@@ -0,0 +1,44 @@
+"""Tests for ClickStack service plugin."""
+
+from click.testing import CliRunner
+
+from phlo_clickstack.cli import clickstack_group
+from phlo_clickstack.plugin import ClickStackServicePlugin
+
+
+def test_clickstack_service_definition() -> None:
+    """Validate ClickStack service definition defaults."""
+    plugin = ClickStackServicePlugin()
+    defn = plugin.service_definition
+
+    assert defn["name"] == "clickstack"
+    assert defn["profile"] == "observability"
+    assert "${CLICKSTACK_PORT:-18080}:8080" in defn["compose"]["ports"]
+    assert "${CLICKSTACK_HTTP_PORT:-18123}:8123" in defn["compose"]["ports"]
+    assert "${CLICKSTACK_NATIVE_PORT:-19002}:9000" in defn["compose"]["ports"]
+    assert not any("4317" in port or "4318" in port for port in defn["compose"]["ports"])
+    assert "clickstack-data:/var/lib/clickhouse" in defn["compose"]["volumes"]
+    assert "./volumes/clickstack:/var/lib/clickhouse" not in defn["compose"]["volumes"]
+
+
+def test_clickstack_plugin_metadata() -> None:
+    """Validate ClickStack plugin metadata."""
+    plugin = ClickStackServicePlugin()
+    meta = plugin.metadata
+
+    assert meta.name == "clickstack"
+    assert "observability" in meta.tags
+
+
+def test_clickstack_query_rejects_partial_phlo_directory(monkeypatch, tmp_path) -> None:
+    """Logging-created .phlo directories are not initialized service projects."""
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".phlo" / "logs").mkdir(parents=True)
+    monkeypatch.setattr("phlo_clickstack.cli._require_container_backend", lambda: None)
+
+    result = CliRunner().invoke(clickstack_group, ["query", "SELECT 1"])
+
+    assert result.exit_code != 0
+    assert "Phlo services have not been initialized" in result.output
+    assert "Missing: .phlo/docker-compose.yml" in result.output
+    assert "Run: phlo services init" in result.output

phlo_clickstack-0.3.0/src/phlo_clickstack/authorization.py

@@ -1,166 +0,0 @@
-"""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.3.0/src/phlo_clickstack/cli_plugin.py

@@ -1,49 +0,0 @@
-"""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/plugin.py

@@ -1,44 +0,0 @@
-"""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/tests/test_clickstack_plugin.py

@@ -1,21 +0,0 @@
-"""Tests for ClickStack service plugin."""
-
-from phlo_clickstack.plugin import ClickStackServicePlugin
-
-
-def test_clickstack_service_definition() -> None:
-    """Validate ClickStack service definition defaults."""
-    plugin = ClickStackServicePlugin()
-    defn = plugin.service_definition
-
-    assert defn["name"] == "clickstack"
-    assert defn["profile"] == "observability"
-
-
-def test_clickstack_plugin_metadata() -> None:
-    """Validate ClickStack plugin metadata."""
-    plugin = ClickStackServicePlugin()
-    meta = plugin.metadata
-
-    assert meta.name == "clickstack"
-    assert "observability" in meta.tags