kctl-prefect 0.5.2__tar.gz

kctl_prefect-0.5.2/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_prefect-0.5.2/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: kctl-prefect
+Version: 0.5.2
+Summary: CLI for managing kodemeio Prefect flow scheduler
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.35.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.8.0
+Requires-Dist: pydantic>=2.10.0
+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>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'

kctl_prefect-0.5.2/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-prefect"
+version = "0.5.2"
+description = "CLI for managing kodemeio Prefect flow scheduler"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.8.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "httpx>=0.28.0",
+    "boto3>=1.35.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+]
+
+[project.scripts]
+kctl-prefect = "kctl_prefect.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_prefect-0.5.2/src/kctl_prefect/__init__.py

@@ -0,0 +1 @@
+"""kctl-prefect — CLI for kodemeio Prefect operations."""

kctl_prefect-0.5.2/src/kctl_prefect/cli.py

@@ -0,0 +1,58 @@
+"""kctl-prefect CLI entry point."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from kctl_prefect.commands.config_cmd import app as config_app
+from kctl_prefect.commands.deployments import app as deployments_app
+from kctl_prefect.commands.flows import app as flows_app
+from kctl_prefect.commands.health import app as health_app
+from kctl_prefect.commands.reports import app as reports_app
+from kctl_prefect.commands.runs import app as runs_app
+from kctl_prefect.core.callbacks import AppContext
+from kctl_lib.tui import add_tui_command
+
+app = typer.Typer(
+    name="kctl-prefect",
+    help="CLI for managing kodemeio Prefect flow scheduler.",
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress info"),
+    profile: str | None = typer.Option(None, "--profile", "-p", help="Config profile"),
+    fmt: str = typer.Option("pretty", "--format", help="Output format"),
+    no_header: bool = typer.Option(False, "--no-header", help="No CSV header"),
+    version: bool = typer.Option(False, "--version", "-V", help="Show version"),
+) -> None:
+    if version:
+        typer.echo("kctl-prefect 0.1.0")
+        raise typer.Exit()
+    ctx.obj = AppContext(json_mode=json_output, quiet=quiet, profile=profile, format=fmt, no_header=no_header)
+
+
+app.add_typer(health_app, name="health")
+app.add_typer(flows_app, name="flows")
+app.add_typer(deployments_app, name="deployments")
+app.add_typer(runs_app, name="runs")
+app.add_typer(reports_app, name="reports")
+app.add_typer(config_app, name="config")
+add_tui_command(app, service_key="prefect", version="0.1.0")
+
+
+def _run() -> None:
+    from kctl_lib.exceptions import KctlError
+
+    try:
+        app()
+    except KctlError as e:
+        typer.echo(f"Error: {e}", err=True)
+        sys.exit(1)

kctl_prefect-0.5.2/src/kctl_prefect/commands/config_cmd.py

@@ -0,0 +1,37 @@
+"""Configuration management."""
+
+from __future__ import annotations
+
+import typer
+
+from kctl_prefect.core.callbacks import AppContext
+from kctl_prefect.core.config import ServiceConfig, resolve_active_profile_name, set_service_config
+
+app = typer.Typer(help="Configuration management", no_args_is_help=True)
+
+
+@app.command("init")
+def init(ctx: typer.Context) -> None:
+    """Interactive config setup."""
+    actx: AppContext = ctx.obj
+    profile = resolve_active_profile_name(actx.profile)
+
+    url = typer.prompt("Prefect API URL", default="http://localhost:4200/api")
+    api_key = typer.prompt("API key (optional, press Enter to skip)", default="")
+    s3_bucket = typer.prompt("S3 bucket for reports", default="kodemeio-prefect")
+
+    cfg = ServiceConfig(url=url, api_key=api_key, s3_bucket=s3_bucket)
+    set_service_config(profile, cfg)
+    actx.output.success(f"Config saved for profile '{profile}'")
+
+
+@app.command("test")
+def test(ctx: typer.Context) -> None:
+    """Test connection to Prefect server."""
+    actx: AppContext = ctx.obj
+    try:
+        actx.client.health()
+        actx.output.success("Connection OK")
+    except Exception as e:
+        actx.output.error(f"Connection failed: {e}")
+        raise typer.Exit(1)

kctl_prefect-0.5.2/src/kctl_prefect/commands/deployments.py

@@ -0,0 +1,52 @@
+"""Deployment management commands."""
+
+from __future__ import annotations
+
+import typer
+
+from kctl_prefect.core.callbacks import AppContext
+
+app = typer.Typer(help="Deployment management", no_args_is_help=True)
+
+
+@app.command("list")
+def list_deployments(ctx: typer.Context) -> None:
+    """List all deployments with schedules."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    deps = actx.client.list_deployments()
+    if out.json_mode:
+        out.raw_json(deps)
+        return
+    rows = []
+    for d in deps:
+        schedules = d.get("schedules", [])
+        cron = schedules[0].get("schedule", {}).get("cron", "N/A") if schedules else "N/A"
+        rows.append([d.get("name", ""), cron, "Paused" if d.get("paused") else "Active", d.get("id", "")])
+    out.table("Deployments", [("Name", "cyan"), ("Schedule", ""), ("Status", ""), ("ID", "dim")], rows)
+
+
+@app.command("pause")
+def pause(ctx: typer.Context, name: str = typer.Argument(help="Deployment name")) -> None:
+    """Pause a deployment schedule."""
+    actx: AppContext = ctx.obj
+    deps = actx.client.list_deployments()
+    dep = next((d for d in deps if d.get("name") == name), None)
+    if not dep:
+        actx.output.error(f"Deployment '{name}' not found")
+        raise typer.Exit(1)
+    actx.client.pause_deployment(dep["id"])
+    actx.output.success(f"Paused: {name}")
+
+
+@app.command("resume")
+def resume(ctx: typer.Context, name: str = typer.Argument(help="Deployment name")) -> None:
+    """Resume a paused deployment."""
+    actx: AppContext = ctx.obj
+    deps = actx.client.list_deployments()
+    dep = next((d for d in deps if d.get("name") == name), None)
+    if not dep:
+        actx.output.error(f"Deployment '{name}' not found")
+        raise typer.Exit(1)
+    actx.client.resume_deployment(dep["id"])
+    actx.output.success(f"Resumed: {name}")

kctl_prefect-0.5.2/src/kctl_prefect/commands/flows.py

@@ -0,0 +1,49 @@
+"""Flow management commands."""
+
+from __future__ import annotations
+
+import typer
+
+from kctl_prefect.core.callbacks import AppContext
+
+app = typer.Typer(help="Flow management", no_args_is_help=True)
+
+
+@app.command("list")
+def list_flows(ctx: typer.Context) -> None:
+    """List all registered flows."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    flows = actx.client.list_flows()
+    if out.json_mode:
+        out.raw_json(flows)
+        return
+    rows = [[f.get("name", ""), f.get("id", "")] for f in flows]
+    out.table("Flows", [("Name", "cyan"), ("ID", "dim")], rows)
+
+
+@app.command("run")
+def run_flow(ctx: typer.Context, name: str = typer.Argument(help="Deployment name")) -> None:
+    """Trigger an ad-hoc flow run."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    deployments = actx.client.list_deployments()
+    dep = next((d for d in deployments if d.get("name") == name), None)
+    if not dep:
+        out.error(f"Deployment '{name}' not found")
+        raise typer.Exit(1)
+    run = actx.client.create_flow_run(dep["id"])
+    out.success(f"Flow run created: {run.get('id', 'unknown')}")
+
+
+@app.command("history")
+def history(ctx: typer.Context, name: str = typer.Argument(help="Flow name"), limit: int = 10) -> None:
+    """Show recent runs for a flow."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    runs = actx.client.list_flow_runs(limit=limit)
+    if out.json_mode:
+        out.raw_json(runs)
+        return
+    rows = [[r.get("name", ""), r.get("state_type", ""), r.get("start_time", ""), r.get("id", "")] for r in runs]
+    out.table("Flow Runs", [("Name", "cyan"), ("State", ""), ("Start", ""), ("ID", "dim")], rows)

kctl_prefect-0.5.2/src/kctl_prefect/commands/health.py

@@ -0,0 +1,22 @@
+"""Health check commands."""
+
+from __future__ import annotations
+
+import typer
+
+from kctl_prefect.core.callbacks import AppContext
+
+app = typer.Typer(help="Health checks", no_args_is_help=True)
+
+
+@app.command("check")
+def check(ctx: typer.Context) -> None:
+    """Check Prefect server health."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    try:
+        actx.client.health()
+        out.success("Prefect server is healthy")
+    except Exception as e:
+        out.error(f"Prefect server unreachable: {e}")
+        raise typer.Exit(1)

kctl_prefect-0.5.2/src/kctl_prefect/commands/reports.py

@@ -0,0 +1,70 @@
+"""S3 report archive browsing."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from kctl_prefect.core.callbacks import AppContext
+
+app = typer.Typer(help="Report archive (S3)", no_args_is_help=True)
+
+
+@app.command("list")
+def list_reports(
+    ctx: typer.Context,
+    flow: str | None = typer.Option(None, help="Filter by flow name"),
+    prefix: str = typer.Option("reports/", help="S3 prefix"),
+) -> None:
+    """List stored reports in S3."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    cfg = actx.config
+
+    import boto3
+
+    s3 = boto3.client(
+        "s3",
+        endpoint_url=cfg.s3_endpoint,
+        aws_access_key_id=cfg.s3_access_key,
+        aws_secret_access_key=cfg.s3_secret_key,
+        region_name=cfg.s3_region,
+    )
+
+    search_prefix = f"reports/{flow}/" if flow else prefix
+    resp = s3.list_objects_v2(Bucket=cfg.s3_bucket, Prefix=search_prefix, MaxKeys=100)
+    objects = resp.get("Contents", [])
+
+    if out.json_mode:
+        out.raw_json([{"key": o["Key"], "size": o["Size"], "modified": str(o["LastModified"])} for o in objects])
+        return
+
+    rows = [[o["Key"], f"{o['Size']:,}", str(o["LastModified"])[:19]] for o in objects]
+    out.table("Reports", [("Key", "cyan"), ("Size", ""), ("Modified", "dim")], rows)
+
+
+@app.command("download")
+def download(
+    ctx: typer.Context,
+    key: str = typer.Argument(help="S3 key"),
+    output_path: str = typer.Option(".", help="Local directory"),
+) -> None:
+    """Download a report from S3."""
+    actx: AppContext = ctx.obj
+    cfg = actx.config
+
+    import boto3
+
+    s3 = boto3.client(
+        "s3",
+        endpoint_url=cfg.s3_endpoint,
+        aws_access_key_id=cfg.s3_access_key,
+        aws_secret_access_key=cfg.s3_secret_key,
+        region_name=cfg.s3_region,
+    )
+
+    filename = Path(key).name
+    local_path = Path(output_path) / filename
+    s3.download_file(cfg.s3_bucket, key, str(local_path))
+    actx.output.success(f"Downloaded: {local_path}")

kctl_prefect-0.5.2/src/kctl_prefect/commands/runs.py

@@ -0,0 +1,75 @@
+"""Flow run inspection commands."""
+
+from __future__ import annotations
+
+import typer
+
+from kctl_prefect.core.callbacks import AppContext
+
+app = typer.Typer(help="Flow run inspection", no_args_is_help=True)
+
+
+@app.command("list")
+def list_runs(
+    ctx: typer.Context,
+    limit: int = typer.Option(20, help="Max results"),
+    state: str | None = typer.Option(None, help="Filter by state"),
+) -> None:
+    """List recent flow runs."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    runs = actx.client.list_flow_runs(limit=limit, state=state)
+    if out.json_mode:
+        out.raw_json(runs)
+        return
+    rows = [[r.get("name", ""), r.get("state_type", ""), r.get("start_time", ""), r.get("id", "")[:8]] for r in runs]
+    out.table("Flow Runs", [("Name", "cyan"), ("State", ""), ("Start", ""), ("ID", "dim")], rows)
+
+
+@app.command("get")
+def get_run(ctx: typer.Context, run_id: str = typer.Argument(help="Flow run ID")) -> None:
+    """Get details of a flow run."""
+    actx: AppContext = ctx.obj
+    run = actx.client.get_flow_run(run_id)
+    if actx.output.json_mode:
+        actx.output.raw_json(run)
+        return
+    actx.output.detail(
+        f"Flow Run: {run.get('name', '')}",
+        sections=[
+            (
+                "Info",
+                [
+                    ("ID", run.get("id", "")),
+                    ("State", run.get("state_type", "")),
+                    ("Start", run.get("start_time", "")),
+                    ("End", run.get("end_time", "")),
+                    ("Duration", run.get("total_run_time", "")),
+                ],
+            ),
+        ],
+    )
+
+
+@app.command("cancel")
+def cancel(ctx: typer.Context, run_id: str = typer.Argument(help="Flow run ID")) -> None:
+    """Cancel a running flow."""
+    actx: AppContext = ctx.obj
+    actx.client.cancel_flow_run(run_id)
+    actx.output.success(f"Cancelling: {run_id}")
+
+
+@app.command("logs")
+def logs(ctx: typer.Context, run_id: str = typer.Argument(help="Flow run ID"), limit: int = 100) -> None:
+    """Show logs for a flow run."""
+    actx: AppContext = ctx.obj
+    log_entries = actx.client.get_flow_run_logs(run_id, limit=limit)
+    if actx.output.json_mode:
+        actx.output.raw_json(log_entries)
+        return
+    for entry in log_entries:
+        ts = entry.get("timestamp", "")[:19]
+        level = entry.get("level", 0)
+        msg = entry.get("message", "")
+        level_name = {10: "DEBUG", 20: "INFO", 30: "WARN", 40: "ERROR"}.get(level, str(level))
+        actx.output.text(f"[{ts}] {level_name}: {msg}")

kctl_prefect-0.5.2/src/kctl_prefect/core/callbacks.py

@@ -0,0 +1,30 @@
+"""Application context with lazy client initialization."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from kctl_lib.callbacks import AppContextBase
+
+from kctl_prefect.core.client import PrefectClient
+from kctl_prefect.core.config import ServiceConfig, get_service_config, resolve_active_profile_name
+
+
+@dataclass
+class AppContext(AppContextBase):
+    _client: PrefectClient | None = field(default=None, repr=False)
+    _config: ServiceConfig | None = field(default=None, repr=False)
+
+    @property
+    def client(self) -> PrefectClient:
+        if self._client is None:
+            cfg = self.config
+            self._client = PrefectClient(base_url=cfg.url, credential=cfg.api_key)
+        return self._client
+
+    @property
+    def config(self) -> ServiceConfig:
+        if self._config is None:
+            profile = resolve_active_profile_name(self.profile)
+            self._config = get_service_config(profile)
+        return self._config

kctl_prefect-0.5.2/src/kctl_prefect/core/client.py

@@ -0,0 +1,55 @@
+"""Prefect REST API client."""
+
+from __future__ import annotations
+
+from kctl_lib.api_client import APIClient
+
+
+class PrefectClient(APIClient):
+    AUTH_HEADER = "Authorization"
+    AUTH_PREFIX = "Bearer"
+    API_PREFIX = "/api"
+
+    def health(self) -> dict:
+        return self.get("/health")
+
+    def list_flows(self) -> list[dict]:
+        resp = self.post("/flows/filter", json={})
+        return resp if isinstance(resp, list) else []
+
+    def list_deployments(self) -> list[dict]:
+        resp = self.post("/deployments/filter", json={})
+        return resp if isinstance(resp, list) else []
+
+    def create_flow_run(self, deployment_id: str) -> dict:
+        return self.post(f"/deployments/{deployment_id}/create_flow_run", json={})
+
+    def list_flow_runs(self, limit: int = 20, state: str | None = None) -> list[dict]:
+        body: dict = {"sort": "EXPECTED_START_TIME_DESC", "limit": limit}
+        if state:
+            body["flow_runs"] = {"state": {"type": {"any_": [state.upper()]}}}
+        resp = self.post("/flow_runs/filter", json=body)
+        return resp if isinstance(resp, list) else []
+
+    def get_flow_run(self, flow_run_id: str) -> dict:
+        return self.get(f"/flow_runs/{flow_run_id}")
+
+    def cancel_flow_run(self, flow_run_id: str) -> None:
+        self.post(f"/flow_runs/{flow_run_id}/set_state", json={"state": {"type": "CANCELLING"}})
+
+    def get_flow_run_logs(self, flow_run_id: str, limit: int = 100) -> list[dict]:
+        resp = self.post(
+            "/logs/filter",
+            json={"logs": {"flow_run_id": {"any_": [flow_run_id]}}, "limit": limit, "sort": "TIMESTAMP_ASC"},
+        )
+        return resp if isinstance(resp, list) else []
+
+    def list_work_pools(self) -> list[dict]:
+        resp = self.post("/work_pools/filter", json={})
+        return resp if isinstance(resp, list) else []
+
+    def pause_deployment(self, deployment_id: str) -> None:
+        self.patch(f"/deployments/{deployment_id}", json={"paused": True})
+
+    def resume_deployment(self, deployment_id: str) -> None:
+        self.patch(f"/deployments/{deployment_id}", json={"paused": False})

kctl_prefect-0.5.2/src/kctl_prefect/core/config.py

@@ -0,0 +1,40 @@
+"""Prefect service configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from kctl_lib.config import (
+    get_service_config as _get_service_config,
+    resolve_active_profile_name as _resolve_active_profile_name,
+    set_service_config as _set_service_config,
+)
+
+SERVICE_KEY = "prefect"
+ENV_PREFIX = "KCTL_PREFECT"
+
+VALID_FIELDS = {"url", "api_key", "s3_bucket", "s3_endpoint", "s3_access_key", "s3_secret_key", "s3_region"}
+
+
+class ServiceConfig(BaseModel):
+    url: str = ""
+    api_key: str = ""
+    s3_bucket: str = ""
+    s3_endpoint: str = ""
+    s3_access_key: str = ""
+    s3_secret_key: str = ""
+    s3_region: str = "fsn1"
+
+
+def get_service_config(profile_name: str) -> ServiceConfig:
+    data = _get_service_config(profile_name, SERVICE_KEY, VALID_FIELDS)
+    return ServiceConfig(**data) if data else ServiceConfig()
+
+
+def set_service_config(profile_name: str, svc_config: ServiceConfig) -> None:
+    cleaned = {k: v for k, v in svc_config.model_dump().items() if v}
+    _set_service_config(profile_name, SERVICE_KEY, cleaned)
+
+
+def resolve_active_profile_name(profile_name: str | None = None) -> str:
+    return _resolve_active_profile_name(profile_name, ENV_PREFIX)