lovarch-cli 0.2.1__py3-none-any.whl

lovarch_cli/clients/lovarch_supabase.py

@@ -0,0 +1,295 @@
+"""LovarchSupabaseClient — DataPersistenceClient via Supabase REST API.
+
+Mirrors LocalSqliteClient but talks to the Lovarch Supabase via PostgREST
+(/rest/v1/{table}) using a user Bearer token managed by LovarchSession
+(auto-refresh on 401).
+
+Tables:
+- pm_squad_executions
+- pm_squad_steps
+- pm_squad_qa_checks
+
+These are the same tables the Lovarch web app writes to — admin pages at
+/admin/squad-execution/{id}/live read them in real time (Story 1.5 will
+verify CLI executions appear in the dashboard alongside web ones).
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime
+from typing import Any
+
+from lovarch_cli.auth.session import LovarchSession, LovarchSessionError
+from lovarch_cli.clients.persistence import (
+    DataPersistenceClient,
+    Execution,
+    ExecutionMode,
+    QaCheck,
+    QaVerdict,
+    Step,
+    StepStatus,
+)
+
+
+def _parse_dt(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    # Supabase returns "2026-05-10T12:00:00.123456+00:00" — Python 3.11+ parses
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _parse_metadata(value: Any) -> dict[str, Any]:
+    if not value:
+        return {}
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return {}
+    return {}
+
+
+class LovarchSupabaseClient(DataPersistenceClient):
+    """Premium-mode persistence backend via Supabase REST."""
+
+    def __init__(self, session: LovarchSession) -> None:
+        self._session = session
+
+    # ─── Helper ───────────────────────────────────────────────────────────
+
+    async def _post(self, table: str, body: dict[str, Any]) -> dict[str, Any]:
+        path = f"/rest/v1/{table}"
+        response = await self._session.request(
+            "POST",
+            path,
+            json=body,
+            headers={
+                "Content-Type": "application/json",
+                "Prefer": "return=representation",
+            },
+        )
+        if response.status_code >= 400:
+            msg = (
+                f"Supabase POST {table} failed: HTTP {response.status_code} "
+                f"{response.text[:300]}"
+            )
+            raise LovarchSessionError(msg)
+        data = response.json()
+        if isinstance(data, list):
+            return data[0] if data else {}
+        return data
+
+    async def _patch(
+        self, table: str, filters: dict[str, str], body: dict[str, Any]
+    ) -> None:
+        path = f"/rest/v1/{table}"
+        response = await self._session.request(
+            "PATCH",
+            path,
+            params=filters,
+            json=body,
+            headers={"Content-Type": "application/json"},
+        )
+        if response.status_code >= 400:
+            msg = (
+                f"Supabase PATCH {table} failed: HTTP {response.status_code} "
+                f"{response.text[:300]}"
+            )
+            raise LovarchSessionError(msg)
+
+    async def _get(
+        self, table: str, params: dict[str, Any]
+    ) -> list[dict[str, Any]]:
+        path = f"/rest/v1/{table}"
+        response = await self._session.request("GET", path, params=params)
+        if response.status_code >= 400:
+            msg = (
+                f"Supabase GET {table} failed: HTTP {response.status_code} "
+                f"{response.text[:300]}"
+            )
+            raise LovarchSessionError(msg)
+        data = response.json()
+        return data if isinstance(data, list) else []
+
+    # ─── DataPersistenceClient impl ───────────────────────────────────────
+
+    async def create_execution(
+        self,
+        project_id: str,
+        workflow: str,
+        mode: ExecutionMode,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        execution_id = str(uuid.uuid4())
+        # Schema reference: pm_squad_executions has columns id, project_id,
+        # workflow, status, started_at, completed_at, metadata. CLI rows
+        # tagged with metadata.source='cli-{free,premium}' for filtering.
+        meta = dict(metadata or {})
+        meta.setdefault("source", f"cli-{mode.value}")
+        meta.setdefault("cli_user_id", self._session.user_id)
+
+        await self._post(
+            "pm_squad_executions",
+            {
+                "id": execution_id,
+                "project_id": project_id,
+                "workflow": workflow,
+                "status": "pending",
+                "metadata": meta,
+            },
+        )
+        return execution_id
+
+    async def update_execution(
+        self,
+        execution_id: str,
+        status: str,
+        completed_at: datetime | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        body: dict[str, Any] = {"status": status}
+        if completed_at is not None:
+            body["completed_at"] = completed_at.isoformat(timespec="seconds")
+        if metadata is not None:
+            body["metadata"] = metadata
+        await self._patch(
+            "pm_squad_executions",
+            {"id": f"eq.{execution_id}"},
+            body,
+        )
+
+    async def insert_step(
+        self,
+        execution_id: str,
+        agent: str,
+        task: str | None,
+        status: StepStatus = StepStatus.TRIAGED,
+    ) -> str:
+        step_id = str(uuid.uuid4())
+        await self._post(
+            "pm_squad_steps",
+            {
+                "id": step_id,
+                "execution_id": execution_id,
+                "agent": agent,
+                "task": task,
+                "status": status.value,
+            },
+        )
+        return step_id
+
+    async def update_step(
+        self,
+        step_id: str,
+        status: StepStatus,
+        artifact_url: str | None = None,
+        error: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        body: dict[str, Any] = {"status": status.value}
+        if status in {StepStatus.DONE, StepStatus.QA_PASS, StepStatus.VALIDATED}:
+            body["completed_at"] = datetime.utcnow().isoformat(timespec="seconds")
+        if artifact_url is not None:
+            body["artifact_url"] = artifact_url
+        if error is not None:
+            body["error"] = error
+        if metadata is not None:
+            body["metadata"] = metadata
+        await self._patch("pm_squad_steps", {"id": f"eq.{step_id}"}, body)
+
+    async def insert_qa_check(
+        self,
+        execution_id: str,
+        qa_agent: str,
+        target_step_id: str | None,
+        verdict: QaVerdict,
+        findings: str | None = None,
+    ) -> str:
+        qa_id = str(uuid.uuid4())
+        await self._post(
+            "pm_squad_qa_checks",
+            {
+                "id": qa_id,
+                "execution_id": execution_id,
+                "qa_agent": qa_agent,
+                "target_step_id": target_step_id,
+                "verdict": verdict.value,
+                "findings": findings,
+            },
+        )
+        return qa_id
+
+    async def get_execution(self, execution_id: str) -> Execution | None:
+        rows = await self._get(
+            "pm_squad_executions",
+            {"id": f"eq.{execution_id}", "select": "*"},
+        )
+        if not rows:
+            return None
+        r = rows[0]
+        meta = _parse_metadata(r.get("metadata"))
+        # Mode is implied by metadata.source='cli-{free,premium}'; default premium
+        source = str(meta.get("source", "cli-premium"))
+        mode = (
+            ExecutionMode.FREE if source.endswith("free") else ExecutionMode.PREMIUM
+        )
+        return Execution(
+            id=r["id"],
+            project_id=r["project_id"],
+            workflow=r["workflow"],
+            mode=mode,
+            status=r["status"],
+            started_at=_parse_dt(r.get("started_at")) or datetime.utcnow(),
+            completed_at=_parse_dt(r.get("completed_at")),
+            metadata=meta,
+        )
+
+    async def list_steps(self, execution_id: str) -> list[Step]:
+        rows = await self._get(
+            "pm_squad_steps",
+            {
+                "execution_id": f"eq.{execution_id}",
+                "select": "*",
+                "order": "started_at.asc",
+            },
+        )
+        return [
+            Step(
+                id=r["id"],
+                execution_id=r["execution_id"],
+                agent=r["agent"],
+                task=r.get("task"),
+                status=StepStatus(r["status"]),
+                started_at=_parse_dt(r.get("started_at")) or datetime.utcnow(),
+                completed_at=_parse_dt(r.get("completed_at")),
+                artifact_url=r.get("artifact_url"),
+                error=r.get("error"),
+                metadata=_parse_metadata(r.get("metadata")),
+            )
+            for r in rows
+        ]
+
+    async def list_qa_checks(self, execution_id: str) -> list[QaCheck]:
+        rows = await self._get(
+            "pm_squad_qa_checks",
+            {
+                "execution_id": f"eq.{execution_id}",
+                "select": "*",
+                "order": "checked_at.asc",
+            },
+        )
+        return [
+            QaCheck(
+                id=r["id"],
+                execution_id=r["execution_id"],
+                qa_agent=r["qa_agent"],
+                target_step_id=r.get("target_step_id"),
+                verdict=QaVerdict(r["verdict"]),
+                findings=r.get("findings"),
+                checked_at=_parse_dt(r.get("checked_at")) or datetime.utcnow(),
+            )
+            for r in rows
+        ]

lovarch_cli/clients/persistence.py

@@ -0,0 +1,166 @@
+"""DataPersistenceClient — abstract interface for execution tracking.
+
+Mirrors the 3 Lovarch tables (pm_squad_executions, pm_squad_steps,
+pm_squad_qa_checks) but lives behind an ABC so the CLI can run against:
+- Free mode:    SQLite local (~/.lovarch/local.db)
+- Premium mode: Lovarch Supabase (Epic 3)
+
+The methods declared here are the MINIMUM surface needed for the squad
+pipeline to track executions. Lead/CRM/billing methods from the original
+LovarchClient (1.000+ lines, 25 methods) are NOT abstracted — they belong
+to premium mode only and live in lovarch_supabase_extras.py (Epic 3).
+
+Status state machine for steps mirrors the squad workflow:
+    Triaged → Routed → InProgress → Returned → QA_Pending
+    QA_Pending → QA_Pass | QA_Reject
+    QA_Pass → Validated → Done
+    QA_Reject → InProgress (retry)
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class StepStatus(str, Enum):
+    """Step lifecycle states (matches squad workflow contract)."""
+
+    TRIAGED = "Triaged"
+    ROUTED = "Routed"
+    IN_PROGRESS = "InProgress"
+    RETURNED = "Returned"
+    QA_PENDING = "QA_Pending"
+    QA_PASS = "QA_Pass"
+    QA_REJECT = "QA_Reject"
+    VALIDATED = "Validated"
+    DONE = "Done"
+
+
+class ExecutionMode(str, Enum):
+    """Backend mode."""
+
+    FREE = "free"
+    PREMIUM = "premium"
+
+
+class QaVerdict(str, Enum):
+    """QA gate verdicts (mirrors Lovarch convention)."""
+
+    PASS = "PASS"
+    CONCERNS = "CONCERNS"
+    FAIL = "FAIL"
+    WAIVED = "WAIVED"
+
+
+@dataclass(frozen=True)
+class Execution:
+    """Squad execution metadata."""
+
+    id: str
+    project_id: str
+    workflow: str
+    mode: ExecutionMode
+    status: str
+    started_at: datetime
+    completed_at: datetime | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Step:
+    """Single agent step within an execution."""
+
+    id: str
+    execution_id: str
+    agent: str
+    task: str | None
+    status: StepStatus
+    started_at: datetime
+    completed_at: datetime | None = None
+    artifact_url: str | None = None
+    error: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class QaCheck:
+    """QA gate verdict on a step."""
+
+    id: str
+    execution_id: str
+    qa_agent: str
+    target_step_id: str | None
+    verdict: QaVerdict
+    findings: str | None
+    checked_at: datetime
+
+
+class DataPersistenceClient(ABC):
+    """Abstract backend for execution + steps + QA tracking."""
+
+    @abstractmethod
+    async def create_execution(
+        self,
+        project_id: str,
+        workflow: str,
+        mode: ExecutionMode,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Create an execution row, return its id."""
+
+    @abstractmethod
+    async def update_execution(
+        self,
+        execution_id: str,
+        status: str,
+        completed_at: datetime | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Update execution status / completion / metadata."""
+
+    @abstractmethod
+    async def insert_step(
+        self,
+        execution_id: str,
+        agent: str,
+        task: str | None,
+        status: StepStatus = StepStatus.TRIAGED,
+    ) -> str:
+        """Insert a new step, return its id."""
+
+    @abstractmethod
+    async def update_step(
+        self,
+        step_id: str,
+        status: StepStatus,
+        artifact_url: str | None = None,
+        error: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Update step status / artifact / error / metadata."""
+
+    @abstractmethod
+    async def insert_qa_check(
+        self,
+        execution_id: str,
+        qa_agent: str,
+        target_step_id: str | None,
+        verdict: QaVerdict,
+        findings: str | None = None,
+    ) -> str:
+        """Record a QA gate verdict, return its id."""
+
+    @abstractmethod
+    async def get_execution(self, execution_id: str) -> Execution | None:
+        """Fetch execution by id."""
+
+    @abstractmethod
+    async def list_steps(self, execution_id: str) -> list[Step]:
+        """List all steps for an execution, ordered by started_at."""
+
+    @abstractmethod
+    async def list_qa_checks(self, execution_id: str) -> list[QaCheck]:
+        """List all QA verdicts for an execution."""

lovarch_cli/clients/storage.py

@@ -0,0 +1,66 @@
+"""StorageClient — abstract interface for artifact persistence.
+
+Two implementations:
+- Free:    LocalFilesystemStorage  → ~/.lovarch/projects/{execution_id}/
+- Premium: LovarchS3Storage        → Lovarch S3 buckets (Epic 3)
+                                       (user-assets, render-images, moodboard-sources)
+
+The squad generates 27 deliverables per execution (DXF, IFC, PDF, XLSX, JSON,
+HTML, ZIP). All go through this interface so the same pipeline_runner code
+works in both modes.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class StoredArtifact:
+    """Reference to a stored artifact."""
+
+    id: str
+    execution_id: str
+    filename: str
+    url: str
+    mime_type: str | None
+    size_bytes: int
+    created_at: datetime
+
+
+class StorageClient(ABC):
+    """Abstract backend for artifact storage (deliverables)."""
+
+    @abstractmethod
+    async def save_artifact(
+        self,
+        execution_id: str,
+        filename: str,
+        data: bytes | Path,
+        mime_type: str | None = None,
+    ) -> StoredArtifact:
+        """Save artifact bytes (or copy from Path) and return reference.
+
+        Args:
+            execution_id: scope artifact to this run
+            filename: target filename (e.g. 'pianta-progetto.dxf')
+            data: raw bytes OR Path to source file
+            mime_type: optional MIME type (defaults to guess by extension)
+        """
+
+    @abstractmethod
+    async def read_artifact(self, artifact_id_or_url: str) -> bytes:
+        """Read an artifact by id or url and return its bytes."""
+
+    @abstractmethod
+    async def list_artifacts(self, execution_id: str) -> list[StoredArtifact]:
+        """List all artifacts for an execution."""
+
+    @abstractmethod
+    async def delete_artifacts(self, execution_id: str) -> int:
+        """Delete all artifacts for an execution (GDPR right-to-erasure).
+
+        Returns number of artifacts deleted.
+        """

lovarch_cli/commands/__init__.py

@@ -0,0 +1,10 @@
+"""lovarch-cli subcommands.
+
+Each command lives in its own module and exposes either:
+- a `cmd()` function (single-action subcommand), OR
+- an `app: typer.Typer` instance (multi-subcommand group)
+
+The main CLI (lovarch_cli/cli.py) registers each via add_typer or command.
+
+Lazy imports here so heavy commands (audit, run) don't load at startup.
+"""