kctl-plausible 0.6.2__py3-none-any.whl

kctl_plausible/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-plausible: Kodemeio Plausible Analytics CLI."""
+
+__version__ = "0.6.2"

kctl_plausible/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m kctl_plausible."""
+
+from kctl_plausible.cli import _run
+
+_run()

kctl_plausible/cli.py

@@ -0,0 +1,97 @@
+"""Main CLI entry point for kctl-plausible."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_plausible import __version__
+from kctl_plausible.commands.config_cmd import app as config_app
+from kctl_plausible.commands.doctor import app as doctor_app
+from kctl_plausible.commands.export import app as export_app
+from kctl_plausible.commands.goals import app as goals_app
+from kctl_plausible.commands.sites import app as sites_app
+from kctl_plausible.commands.stats import app as stats_app
+from kctl_plausible.core.callbacks import AppContext
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-plausible {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-plausible",
+    help="Kodemeio Plausible Analytics CLI - query and manage your Plausible CE instance.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON (shortcut for --format json)")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    output_format: Annotated[
+        str, typer.Option("--format", "-f", help="Output format: pretty, json, csv, yaml")
+    ] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit headers in CSV output")] = False,
+    debug: Annotated[bool, typer.Option("--debug", help="Enable debug logging")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    url: Annotated[str | None, typer.Option("--url", help="API URL override")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="API key override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Plausible Analytics CLI."""
+    import os
+
+    if debug:
+        os.environ["KCTL_DEBUG"] = "1"
+
+    effective_format = "json" if json_output else output_format
+
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output or effective_format == "json",
+        quiet=quiet,
+        format=effective_format,
+        no_header=no_header,
+        debug=debug,
+        profile=profile,
+        url_override=url,
+        api_key_override=api_key,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-plausible", __version__)
+
+
+# ---------------------------------------------------------------------------
+# Command groups
+# ---------------------------------------------------------------------------
+app.add_typer(config_app, name="config")
+app.add_typer(stats_app, name="stats")
+app.add_typer(sites_app, name="sites")
+app.add_typer(goals_app, name="goals")
+app.add_typer(export_app, name="export")
+app.add_typer(doctor_app, name="doctor")
+add_tui_command(app, service_key="plausible", version=__version__)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_plausible/commands/config_cmd.py

@@ -0,0 +1,105 @@
+"""Configuration management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+from kctl_plausible.core.config import (
+    CONFIG_FILE,
+    SERVICE_KEY,
+    ServiceConfig,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    resolve_active_profile_name,
+    set_default_profile,
+    set_service_config,
+)
+
+app = typer.Typer(help="Manage CLI configuration and profiles.")
+
+
+def _mask(val: str) -> str:
+    if not val:
+        return "[dim]not set[/dim]"
+    return f"{val[:4]}{'*' * max(0, len(val) - 8)}{val[-4:]}" if len(val) > 10 else "****"
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    url: Annotated[str | None, typer.Option("--url")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key")] = None,
+    name: Annotated[str | None, typer.Option("--name", "-n")] = None,
+) -> None:
+    """Initialize CLI configuration."""
+    c: AppContext = ctx.obj
+    out = c.output
+    profile_name = name or typer.prompt("Profile name", default="kodemeio")
+    api_url = url or typer.prompt("Plausible URL (e.g. https://plausible.example.com)")
+    key = api_key or typer.prompt("API key", hide_input=True)
+
+    svc = ServiceConfig(url=api_url, api_key=key)
+    set_service_config(profile_name, svc)
+    if len(get_profile_names()) <= 1:
+        set_default_profile(profile_name)
+    out.success(f"Configuration saved to {CONFIG_FILE}")
+    out.kv("Profile", profile_name)
+    out.kv("URL", api_url)
+    out.kv("API Key", _mask(key))
+
+
+@app.command()
+def show(ctx: typer.Context) -> None:
+    """Show configuration (keys masked)."""
+    c: AppContext = ctx.obj
+    out = c.output
+    default = get_default_profile()
+    sections = [
+        (
+            "General",
+            [
+                ("Config file", str(CONFIG_FILE)),
+                ("Default profile", default),
+                ("Service key", SERVICE_KEY),
+            ],
+        )
+    ]
+    for pname in get_profile_names():
+        marker = " [green](default)[/green]" if pname == default else ""
+        services = get_all_services_in_profile(pname)
+        kvs = []
+        for svc_name, svc_data in services.items():
+            if not isinstance(svc_data, dict):
+                continue
+            indicator = "[green]●[/green]" if svc_name == SERVICE_KEY else "[dim]○[/dim]"
+            kvs.append(
+                (
+                    f"{indicator} {svc_name}",
+                    f"{svc_data.get('url', '')}  key: {_mask(svc_data.get('api_key', ''))}",
+                )
+            )
+        sections.append((f"Profile: {pname}{marker}", kvs or [("(empty)", "")]))
+    out.detail("Configuration", sections)
+
+
+@app.command()
+def test(ctx: typer.Context) -> None:
+    """Test API connection."""
+    c: AppContext = ctx.obj
+    out = c.output
+    active = resolve_active_profile_name(c.profile)
+    out.info(f"Testing profile '{active}' → {SERVICE_KEY}")
+    try:
+        status = c.client.check_health()
+        if status == 200:
+            out.success("Connected to Plausible Analytics API")
+        else:
+            out.error(f"Connection failed: HTTP {status}")
+            raise typer.Exit(1)
+    except Exception as e:
+        out.error(f"Connection failed: {e}")
+        raise typer.Exit(1) from e

kctl_plausible/commands/doctor.py

@@ -0,0 +1,82 @@
+"""Doctor diagnostic checks for kctl-plausible."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import typer
+from kctl_lib.doctor_base import CheckResult, DoctorCheck, run_doctor
+
+from kctl_plausible.core.callbacks import AppContext
+
+
+@dataclass
+class APIConnectivityCheck:
+    """Check that the configured API endpoint is reachable."""
+
+    name: str = "API Connectivity"
+
+    def run(self) -> CheckResult:
+        try:
+            from kctl_plausible.core.config import get_service_config, resolve_active_profile_name
+
+            profile = resolve_active_profile_name()
+            cfg = get_service_config(profile)
+            url = cfg.url or ""
+            if not url:
+                return CheckResult(
+                    name=self.name,
+                    status="fail",
+                    message="No URL configured",
+                    fix_command="kctl-plausible config init",
+                )
+            return CheckResult(name=self.name, status="ok", message=f"URL: {url}")
+        except Exception as e:
+            return CheckResult(name=self.name, status="warn", message=str(e))
+
+
+@dataclass
+class AuthCheck:
+    """Check that authentication credentials are configured."""
+
+    name: str = "Authentication"
+
+    def run(self) -> CheckResult:
+        try:
+            from kctl_plausible.core.config import get_service_config, resolve_active_profile_name
+
+            profile = resolve_active_profile_name()
+            cfg = get_service_config(profile)
+            token = cfg.api_key or ""
+            if not token:
+                return CheckResult(
+                    name=self.name,
+                    status="fail",
+                    message="No API key configured",
+                    fix_command="kctl-plausible config init",
+                )
+            masked = token[:4] + "****" + token[-4:] if len(token) > 8 else "****"
+            return CheckResult(name=self.name, status="ok", message=f"API key configured ({masked})")
+        except Exception as e:
+            return CheckResult(name=self.name, status="warn", message=str(e))
+
+
+app = typer.Typer(help="Run diagnostic checks.", no_args_is_help=False, invoke_without_command=True)
+
+
+@app.callback(invoke_without_command=True)
+def doctor(ctx: typer.Context) -> None:
+    """Run all diagnostic checks."""
+    if ctx.invoked_subcommand is not None:
+        return
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    checks: list[DoctorCheck] = [
+        APIConnectivityCheck(),
+        AuthCheck(),
+    ]
+
+    all_passed = run_doctor(checks, out)  # type: ignore[arg-type]
+    if not all_passed:
+        raise typer.Exit(code=1)

kctl_plausible/commands/export.py

@@ -0,0 +1,99 @@
+"""Export commands for Plausible Analytics.
+
+Export breakdown data as CSV or JSON to stdout or file.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from io import StringIO
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+
+app = typer.Typer(help="Export Plausible stats data.")
+
+
+def _fetch_breakdown(c: AppContext, site_id: str, period: str, prop: str, metrics: str, limit: int) -> list[dict]:
+    """Fetch breakdown data from the API."""
+    params: dict[str, str | int] = {
+        "site_id": site_id,
+        "period": period,
+        "property": prop,
+        "metrics": metrics,
+        "limit": limit,
+    }
+    result = c.client.get("/stats/breakdown", params=params)
+    if isinstance(result, dict) and "results" in result:
+        return result["results"]
+    if isinstance(result, list):
+        return result
+    return []
+
+
+@app.command("csv")
+def csv_cmd(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    prop: Annotated[
+        str, typer.Option("--property", help="Breakdown property: visit:source, visit:page, etc.")
+    ] = "visit:source",
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period")] = "30d",
+    metrics: Annotated[str, typer.Option("--metrics", "-m", help="Comma-separated metrics")] = "visitors,pageviews",
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Max results")] = 100,
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Output file path (default: stdout)")] = None,
+) -> None:
+    """Export breakdown stats as CSV."""
+    c: AppContext = ctx.obj
+    rows = _fetch_breakdown(c, site_id, period, prop, metrics, limit)
+
+    if not rows:
+        c.output.info("No data to export.")
+        return
+
+    columns = list(rows[0].keys())
+    buf = StringIO()
+    writer = csv.DictWriter(buf, fieldnames=columns)
+    writer.writeheader()
+    writer.writerows(rows)
+
+    csv_content = buf.getvalue()
+    if output:
+        with open(output, "w", encoding="utf-8") as f:
+            f.write(csv_content)
+        c.output.success(f"Exported {len(rows)} rows to {output}")
+    else:
+        sys.stdout.write(csv_content)
+
+
+@app.command("json")
+def json_cmd(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    prop: Annotated[
+        str, typer.Option("--property", help="Breakdown property: visit:source, visit:page, etc.")
+    ] = "visit:source",
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period")] = "30d",
+    metrics: Annotated[str, typer.Option("--metrics", "-m", help="Comma-separated metrics")] = "visitors,pageviews",
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Max results")] = 100,
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Output file path (default: stdout)")] = None,
+) -> None:
+    """Export breakdown stats as JSON."""
+    c: AppContext = ctx.obj
+    rows = _fetch_breakdown(c, site_id, period, prop, metrics, limit)
+
+    if not rows:
+        c.output.info("No data to export.")
+        return
+
+    json_content = json.dumps(rows, indent=2)
+    if output:
+        with open(output, "w", encoding="utf-8") as f:
+            f.write(json_content)
+        c.output.success(f"Exported {len(rows)} rows to {output}")
+    else:
+        sys.stdout.write(json_content + "\n")

kctl_plausible/commands/goals.py

@@ -0,0 +1,82 @@
+"""Goal management commands for Plausible Analytics.
+
+Supports listing, creating, and deleting goals for a site.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Plausible goals.")
+
+
+@app.command("list")
+def list_cmd(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+) -> None:
+    """List all goals for a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get("/sites/goals", params={"site_id": site_id})
+    if isinstance(result, dict) and "goals" in result:
+        goals = result["goals"]
+    elif isinstance(result, list):
+        goals = result
+    else:
+        goals = [result] if result else []
+
+    out.table(goals, columns=["id", "goal_type", "event_name", "page_path"], title=f"Goals — {site_id}")
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain")],
+    goal_type: Annotated[str, typer.Option("--type", "-t", help="Goal type: event or page_path")] = "event",
+    event_name: Annotated[str | None, typer.Option("--event-name", "-e", help="Event name (for event goals)")] = None,
+    page_path: Annotated[str | None, typer.Option("--page-path", help="Page path (for page_path goals)")] = None,
+) -> None:
+    """Create a new goal for a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+
+    payload: dict[str, str] = {"site_id": site_id, "goal_type": goal_type}
+    if goal_type == "event":
+        if not event_name:
+            out.error("--event-name is required for event goals")
+            raise typer.Exit(1)
+        payload["event_name"] = event_name
+    elif goal_type == "page_path":
+        if not page_path:
+            out.error("--page-path is required for page_path goals")
+            raise typer.Exit(1)
+        payload["page_path"] = page_path
+    else:
+        out.error(f"Unknown goal type: {goal_type}. Use 'event' or 'page_path'.")
+        raise typer.Exit(1)
+
+    result = c.client.post("/sites/goals", json=payload)
+    out.success(f"Goal created for {site_id}")
+    out.raw_json(result)
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain")],
+    goal_id: Annotated[int, typer.Argument(help="Goal ID to delete")],
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation")] = False,
+) -> None:
+    """Delete a goal from a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    if not force:
+        typer.confirm(f"Delete goal {goal_id} from site '{site_id}'?", abort=True)
+
+    c.client.delete(f"/sites/goals/{goal_id}", params={"site_id": site_id})
+    out.success(f"Goal {goal_id} deleted from {site_id}")

kctl_plausible/commands/sites.py

@@ -0,0 +1,72 @@
+"""Site management commands for Plausible Analytics.
+
+Supports listing, creating, deleting, and getting info on sites.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Plausible sites.")
+
+
+@app.command("list")
+def list_cmd(ctx: typer.Context) -> None:
+    """List all sites."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get("/sites")
+    if isinstance(result, dict) and "sites" in result:
+        sites = result["sites"]
+    elif isinstance(result, list):
+        sites = result
+    else:
+        sites = [result] if result else []
+
+    out.table(sites, columns=["domain", "timezone"], title="Plausible Sites")
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    domain: Annotated[str, typer.Argument(help="Domain to add (e.g. example.com)")],
+    timezone: Annotated[str, typer.Option("--timezone", "-tz", help="Timezone (e.g. Europe/London)")] = "Etc/UTC",
+) -> None:
+    """Create (provision) a new site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.post("/sites", json={"domain": domain, "timezone": timezone})
+    out.success(f"Site created: {domain}")
+    out.raw_json(result)
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain to delete")],
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation")] = False,
+) -> None:
+    """Delete a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    if not force:
+        typer.confirm(f"Delete site '{site_id}'? This cannot be undone.", abort=True)
+
+    c.client.delete(f"/sites/{site_id}")
+    out.success(f"Site deleted: {site_id}")
+
+
+@app.command()
+def info(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain to get info for")],
+) -> None:
+    """Get site details."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get(f"/sites/{site_id}")
+    out.raw_json(result)

kctl_plausible/commands/stats.py

@@ -0,0 +1,128 @@
+"""Stats commands for Plausible Analytics.
+
+Covers realtime visitors, aggregate stats, breakdowns, and timeseries.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_plausible.core.callbacks import AppContext
+
+app = typer.Typer(help="Query Plausible Analytics stats.")
+
+
+@app.command()
+def realtime(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+) -> None:
+    """Get current realtime visitors count."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get("/stats/realtime/visitors", params={"site_id": site_id})
+    out.kv("Site", site_id)
+    out.kv("Realtime Visitors", str(result))
+
+
+@app.command()
+def aggregate(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period: day, 7d, 30d, month, 6mo, 12mo")] = "30d",
+    metrics: Annotated[
+        str,
+        typer.Option("--metrics", "-m", help="Comma-separated metrics: visitors,pageviews,bounce_rate,visit_duration"),
+    ] = "visitors,pageviews,bounce_rate,visit_duration",
+    date: Annotated[str | None, typer.Option("--date", help="Date (YYYY-MM-DD) for the period")] = None,
+    filters: Annotated[str | None, typer.Option("--filters", help="Plausible filter expression")] = None,
+) -> None:
+    """Get aggregate stats for a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str] = {"site_id": site_id, "period": period, "metrics": metrics}
+    if date:
+        params["date"] = date
+    if filters:
+        params["filters"] = filters
+
+    result = c.client.get("/stats/aggregate", params=params)
+    if isinstance(result, dict) and "results" in result:
+        results = result["results"]
+        rows = [{"metric": k, "value": v.get("value", v) if isinstance(v, dict) else v} for k, v in results.items()]
+        out.table(rows, columns=["metric", "value"], title=f"Aggregate Stats — {site_id} ({period})")
+    else:
+        out.raw_json(result)
+
+
+@app.command()
+def breakdown(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    prop: Annotated[
+        str, typer.Option("--property", help="Breakdown property: visit:source, visit:page, etc.")
+    ] = "visit:source",
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period: day, 7d, 30d, month, 6mo, 12mo")] = "30d",
+    metrics: Annotated[str, typer.Option("--metrics", "-m", help="Comma-separated metrics")] = "visitors,pageviews",
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Max results to return")] = 10,
+    date: Annotated[str | None, typer.Option("--date", help="Date (YYYY-MM-DD) for the period")] = None,
+    filters: Annotated[str | None, typer.Option("--filters", help="Plausible filter expression")] = None,
+) -> None:
+    """Get breakdown stats by a property."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str | int] = {
+        "site_id": site_id,
+        "period": period,
+        "property": prop,
+        "metrics": metrics,
+        "limit": limit,
+    }
+    if date:
+        params["date"] = date
+    if filters:
+        params["filters"] = filters
+
+    result = c.client.get("/stats/breakdown", params=params)
+    if isinstance(result, dict) and "results" in result:
+        rows = result["results"]
+        # Determine columns from first row
+        if rows:
+            columns = list(rows[0].keys())
+        else:
+            columns = [prop.split(":")[-1], "visitors"]
+        out.table(rows, columns=columns, title=f"Breakdown by {prop} — {site_id} ({period})")
+    else:
+        out.raw_json(result)
+
+
+@app.command()
+def timeseries(
+    ctx: typer.Context,
+    site_id: Annotated[str, typer.Argument(help="Site domain (e.g. example.com)")],
+    period: Annotated[str, typer.Option("--period", "-p", help="Time period: day, 7d, 30d, month, 6mo, 12mo")] = "30d",
+    metrics: Annotated[str, typer.Option("--metrics", "-m", help="Comma-separated metrics")] = "visitors,pageviews",
+    date: Annotated[str | None, typer.Option("--date", help="Date (YYYY-MM-DD) for the period")] = None,
+    filters: Annotated[str | None, typer.Option("--filters", help="Plausible filter expression")] = None,
+) -> None:
+    """Get timeseries stats for a site."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str] = {"site_id": site_id, "period": period, "metrics": metrics}
+    if date:
+        params["date"] = date
+    if filters:
+        params["filters"] = filters
+
+    result = c.client.get("/stats/timeseries", params=params)
+    if isinstance(result, dict) and "results" in result:
+        rows = result["results"]
+        if rows:
+            columns = list(rows[0].keys())
+        else:
+            columns = ["date", "visitors"]
+        out.table(rows, columns=columns, title=f"Timeseries — {site_id} ({period})")
+    else:
+        out.raw_json(result)

kctl_plausible/core/callbacks.py

@@ -0,0 +1,39 @@
+"""Typer global callback and shared context for kctl-plausible.
+
+Subclasses AppContextBase from kctl-lib with Plausible Analytics-specific fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from kctl_lib.callbacks import AppContextBase
+
+from kctl_plausible.core.client import PlausibleClient
+from kctl_plausible.core.config import resolve_connection
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """Plausible Analytics-specific application context."""
+
+    debug: bool = False
+    url_override: str | None = None
+    api_key_override: str | None = None
+    _client: PlausibleClient | None = field(default=None, repr=False, init=False)
+
+    @property
+    def client(self) -> PlausibleClient:
+        if self._client is None:
+            url, api_key = resolve_connection(
+                profile_name=self.profile,
+                url_override=self.url_override,
+                api_key_override=self.api_key_override,
+            )
+            self._client = PlausibleClient(base_url=url, api_key=api_key)
+        return self._client
+
+    def close(self) -> None:
+        """Close underlying HTTP client."""
+        if self._client is not None:
+            self._client.close()

kctl_plausible/core/client.py

@@ -0,0 +1,61 @@
+"""Plausible Analytics API client, subclassing kctl-lib's APIClient.
+
+Provides Plausible-specific auth (Authorization: Bearer <key>),
+retry support, and health check functionality.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from kctl_lib.api_client import APIClient
+from kctl_lib.exceptions import ConfigError
+
+
+class PlausibleClient(APIClient):
+    """Synchronous httpx client for Plausible Analytics API with retry support."""
+
+    AUTH_HEADER = "Authorization"
+    AUTH_PREFIX = "Bearer "
+    API_PREFIX = "/api/v1"
+
+    def __init__(
+        self,
+        base_url: str = "",
+        api_key: str = "",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        retry_base_delay: float = 2.0,
+        retry_max_delay: float = 60.0,
+        **kwargs: Any,
+    ):
+        if not base_url:
+            raise ConfigError("No URL configured. Run: kctl-plausible config init")
+
+        super().__init__(
+            base_url=base_url,
+            credential=api_key or "unset",
+            timeout=timeout,
+            retry_enabled=True,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+            retry_max_delay=retry_max_delay,
+            **kwargs,
+        )
+
+    @property
+    def root_url(self) -> str:
+        """Public accessor for the root URL (without /api/v1)."""
+        return self._base_url.rsplit("/api/v1", 1)[0]
+
+    def check_health(self) -> int:
+        """Check health by hitting /api/health (not under /v1), returns HTTP status code."""
+        try:
+            r = httpx.get(
+                f"{self.root_url}/api/health",
+                timeout=5,
+            )
+            return r.status_code
+        except httpx.HTTPError:
+            return 0

kctl_plausible/core/config.py

@@ -0,0 +1,134 @@
+"""Profile management and configuration resolution for kctl-plausible.
+
+Delegates to kctl-lib's config framework with Plausible Analytics-specific settings.
+"""
+
+from __future__ import annotations
+
+import os
+
+from kctl_lib.config import (
+    CONFIG_DIR,
+    CONFIG_FILE,
+    ConfigFile,
+    expand_env,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    is_service_scoped,
+    load_config,
+    load_raw_config,
+    remove_profile,
+    save_raw_config,
+    set_default_profile,
+)
+from kctl_lib.config import get_service_config as _get_service_config
+from kctl_lib.config import (
+    resolve_active_profile_name as _resolve_active_profile_name,
+)
+from kctl_lib.config import set_service_config as _set_service_config
+from pydantic import BaseModel
+
+# This CLI's service key within a profile
+SERVICE_KEY = "plausible"
+
+# Environment variable prefix for this CLI
+ENV_PREFIX = "KCTL_PLAUSIBLE"
+
+__all__ = [
+    "CONFIG_DIR",
+    "CONFIG_FILE",
+    "ConfigFile",
+    "SERVICE_KEY",
+    "ServiceConfig",
+    "get_all_services_in_profile",
+    "get_default_profile",
+    "get_profile_names",
+    "get_service_config",
+    "is_service_scoped",
+    "load_config",
+    "load_raw_config",
+    "remove_profile",
+    "resolve_active_profile_name",
+    "resolve_connection",
+    "save_raw_config",
+    "set_default_profile",
+    "set_service_config",
+]
+
+
+class ServiceConfig(BaseModel):
+    """Plausible Analytics service-specific config within a profile."""
+
+    url: str = ""
+    api_key: str = ""
+
+
+def get_service_config(profile_name: str) -> ServiceConfig:
+    """Get Plausible service config from a profile."""
+    raw = _get_service_config(
+        profile_name,
+        SERVICE_KEY,
+        valid_fields=list(ServiceConfig.model_fields.keys()),
+    )
+    if not raw:
+        return ServiceConfig()
+    return ServiceConfig(**raw)
+
+
+def set_service_config(profile_name: str, svc_config: ServiceConfig) -> None:
+    """Write Plausible service config into a profile."""
+    svc_data = svc_config.model_dump(exclude_defaults=False)
+    # Remove empty values
+    cleaned = {k: v for k, v in svc_data.items() if v}
+    _set_service_config(profile_name, SERVICE_KEY, cleaned)
+
+
+def _expand_key(api_key: str) -> str:
+    """Expand ${ENV_VAR} references in API key values."""
+    return expand_env(api_key)
+
+
+def resolve_active_profile_name(
+    profile_name: str | None = None,
+) -> str:
+    """Resolve the active profile name from all sources."""
+    return _resolve_active_profile_name(profile_name, ENV_PREFIX)
+
+
+def resolve_connection(
+    profile_name: str | None = None,
+    url_override: str | None = None,
+    api_key_override: str | None = None,
+) -> tuple[str, str]:
+    """Resolve API URL and API key from all sources.
+
+    Priority:
+    1. CLI flags (url_override, api_key_override)
+    2. KCTL_PLAUSIBLE_URL / KCTL_PLAUSIBLE_API_KEY env vars
+    3. Profile's plausible service config
+    """
+    url = ""
+    api_key = ""
+
+    # 3. Config file profile (service-scoped)
+    pname = resolve_active_profile_name(profile_name)
+    svc = get_service_config(pname)
+    if svc.url:
+        url = svc.url
+    if svc.api_key:
+        api_key = svc.api_key
+
+    # 2. KCTL env vars
+    if env_url := os.environ.get("KCTL_PLAUSIBLE_URL"):
+        url = env_url
+    if env_key := os.environ.get("KCTL_PLAUSIBLE_API_KEY"):
+        api_key = env_key
+
+    # 1. CLI flags
+    if url_override:
+        url = url_override
+    if api_key_override:
+        api_key = api_key_override
+
+    return url, api_key

kctl_plausible-0.6.2.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-plausible
+Version: 0.6.2
+Summary: Kodemeio Plausible Analytics CLI — manage Plausible CE via Stats API v1
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.7.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_plausible-0.6.2.dist-info/RECORD

@@ -0,0 +1,18 @@
+kctl_plausible/__init__.py,sha256=_g9qyEyE0ijIixgERgiIpRJJj0mSVKUs4vdAsrATZIg,79
+kctl_plausible/__main__.py,sha256=ehDZi0zjeWZXAPrBz92BFaFTch8eC9Z3f8MdwIfeiMc,95
+kctl_plausible/cli.py,sha256=UYaE7XfMzBxxLGem22IoJO800Fy6PYENSfShW90NCCQ,3366
+kctl_plausible/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kctl_plausible/commands/config_cmd.py,sha256=wUIbVUVwACR51hw2IsvSlsVcWk6_YnG7SJ-OwgDgeHI,3333
+kctl_plausible/commands/doctor.py,sha256=58H8A_HtzTtCh2MoTj4VPhud_XI5Fj83D8ILWWZ81tk,2656
+kctl_plausible/commands/export.py,sha256=XuSa3AJ3iw4QnbQMBr_KzC5HarBM-k67vVo9iXY-o9g,3441
+kctl_plausible/commands/goals.py,sha256=LzOU8evTlOLXLuMZrI-9K8PjZ8AZZWZOWBnAC4eXVSc,2816
+kctl_plausible/commands/sites.py,sha256=2SdarjBgNNyelOHX9iqWOkMOSdAY8rR0WvcdtmGVOqk,2047
+kctl_plausible/commands/stats.py,sha256=GAK2nDN4oVDHI1HxbOiGbClvKqdBiny5OCYsMzSQB4A,5023
+kctl_plausible/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kctl_plausible/core/callbacks.py,sha256=sNlKC0MYnexWN3pi3BOCploFBge8R4_3osTHmsyh1Os,1223
+kctl_plausible/core/client.py,sha256=bthvcVP6dLnVXGgG1Q4Garm9Y4cpJchCRSW0ohQ4Gq8,1752
+kctl_plausible/core/config.py,sha256=2FAy9jfbr79S-ZHLEDpcOlc8PrtCtLbpaNpjz8CnTxY,3522
+kctl_plausible-0.6.2.dist-info/METADATA,sha256=kAiUXnYYzevB4mjluvFAeJrQ8oJfJLhfuuvX20B_Ong,598
+kctl_plausible-0.6.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+kctl_plausible-0.6.2.dist-info/entry_points.txt,sha256=ePzwAjS66pMq6Yp2TE4H1MbHkm70QO6ZLsvO64CBo5E,59
+kctl_plausible-0.6.2.dist-info/RECORD,,

kctl_plausible-0.6.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kctl_plausible-0.6.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kctl-plausible = kctl_plausible.cli:_run