plugsync-cli 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

plugsync_cli/client.py

@@ -1,10 +1,81 @@
 """HTTP client wrapper for PluSync REST API."""
+import json
+
 import httpx
 
 from plugsync_cli.compat import check_api_compat
 from plugsync_cli.config import get_api_key, get_api_url
 
 
+class DraftConflict(Exception):
+    """The draft moved on since the version the caller read.
+
+    Carries the draft version the server currently holds, so a command can tell
+    the user what to re-pull instead of surfacing a bare 409.
+    """
+
+    def __init__(self, current_version: int | None):
+        self.current_version = current_version
+        super().__init__(
+            "the connector draft changed since it was pulled"
+            + (f" (server is at draft v{current_version})" if current_version else "")
+        )
+
+
+def _render_detail(detail) -> str:
+    """The backend's `detail` as one readable block.
+
+    FastAPI answers a string for a hand-raised HTTPException, a dict for the
+    structured ones (draft conflicts, upgrade payloads), and a list of
+    per-field entries for a request-validation failure. The last one carries
+    the precise Pydantic error, which is exactly what an operator who mistyped
+    a config key needs to see.
+    """
+    if isinstance(detail, str):
+        return detail
+    if isinstance(detail, list):
+        lines = []
+        for entry in detail:
+            if isinstance(entry, dict) and "msg" in entry:
+                location = ".".join(str(part) for part in entry.get("loc", []))
+                lines.append(f"{location}: {entry['msg']}" if location else entry["msg"])
+            else:
+                lines.append(json.dumps(entry, ensure_ascii=False))
+        return "\n  ".join([""] + lines)
+    return json.dumps(detail, ensure_ascii=False, indent=2)
+
+
+def describe_http_error(exc: httpx.HTTPStatusError) -> str:
+    """A non-2xx turned into something an operator can act on.
+
+    Without this the CLI dies on the raw `raise_for_status()` traceback and
+    throws away the response body, which is where the backend says what is
+    actually wrong.
+    """
+    response, request = exc.response, exc.request
+    summary = (
+        f"{request.method} {request.url.path} failed "
+        f"(HTTP {response.status_code} {response.reason_phrase})"
+    )
+    try:
+        payload = response.json()
+    except ValueError:
+        body = (response.text or "").strip()
+        return f"{summary}: {body}" if body else summary
+
+    detail = payload.get("detail", payload) if isinstance(payload, dict) else payload
+    return f"{summary}: {_render_detail(detail)}"
+
+
+def _conflict_version(response: httpx.Response) -> int | None:
+    """The `current_version` the draft API reports in its 409 detail."""
+    try:
+        detail = response.json().get("detail")
+    except ValueError:
+        return None
+    return detail.get("current_version") if isinstance(detail, dict) else None
+
+
 class PlugSyncClient:
     """Thin wrapper around httpx for PluSync API calls."""
 
@@ -49,36 +120,58 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
-    def export_working_state(self, connector_id: str) -> bytes:
+    def get_draft(self, connector_id: str) -> dict:
+        """The connector's editable config (backend DraftResponse).
+
+        The draft is the CLI's read AND write surface for the current config:
+        there is no server-side export, the config travels as JSON and the
+        directory format is produced locally by `serializer.py` (#1241).
+        """
         with self._client() as c:
-            r = c.get(self._url(f"/connectors/{connector_id}/export"))
+            r = c.get(self._url(f"/connectors/{connector_id}/draft"))
             r.raise_for_status()
-            return r.content
+            return r.json()
 
-    def export_revision(self, connector_id: str, version: int) -> bytes:
+    def put_draft(
+        self, connector_id: str, config: dict, expected_version: int | None = None
+    ) -> dict:
+        """Replace the whole draft config. Never publishes.
+
+        `expected_version` is the `draft_version` the caller last read: the
+        backend rejects the write with 409 if the draft moved on since, which
+        is what keeps a `pull` -> edit -> `push` cycle from silently discarding
+        someone else's dashboard edit. Raises `DraftConflict` on that 409.
+        """
+        params = {} if expected_version is None else {"expected_version": expected_version}
         with self._client() as c:
-            r = c.get(self._url(f"/connectors/{connector_id}/revisions/{version}/export"))
+            r = c.put(
+                self._url(f"/connectors/{connector_id}/draft"),
+                json=config,
+                params=params,
+            )
+            if r.status_code == 409:
+                raise DraftConflict(_conflict_version(r))
             r.raise_for_status()
-            return r.content
+            return r.json()
 
-    def import_zip(self, connector_id: str, zip_data: bytes) -> dict:
+    def get_version(self, connector_id: str, version: int) -> dict:
+        """One published config version, config included (backend VersionResponse)."""
         with self._client() as c:
-            r = c.post(
-                self._url(f"/connectors/{connector_id}/import"),
-                files={"file": ("connector.zip", zip_data, "application/zip")},
-            )
+            r = c.get(self._url(f"/connectors/{connector_id}/versions/{version}"))
             r.raise_for_status()
             return r.json()
 
-    def validate(self, connector_id: str) -> dict:
+    def preflight(self, connector_id: str) -> dict:
+        """Preflight findings on the draft, split into errors/warnings/infos."""
         with self._client() as c:
-            r = c.post(self._url(f"/connectors/{connector_id}/validate"))
+            r = c.get(self._url(f"/connectors/{connector_id}/preflight"))
             r.raise_for_status()
             return r.json()
 
     def preview(self, connector_id: str) -> dict:
+        """What publishing the draft would change against the active version."""
         with self._client() as c:
-            r = c.post(self._url(f"/connectors/{connector_id}/preview"))
+            r = c.get(self._url(f"/connectors/{connector_id}/preview"))
             r.raise_for_status()
             return r.json()
 
@@ -92,14 +185,24 @@ class PlugSyncClient:
             return r.json()
 
     def list_revisions(self, connector_id: str) -> list[dict]:
+        """Published config versions, newest first (backend: app/api/versions.py).
+
+        The endpoint is `/versions`: Plan 6a replaced the `/revisions` API the
+        CLI used to call, which is why `plugsync log` answered 404 (#1244).
+        """
         with self._client() as c:
-            r = c.get(self._url(f"/connectors/{connector_id}/revisions"))
+            r = c.get(self._url(f"/connectors/{connector_id}/versions"))
             r.raise_for_status()
             return r.json()
 
     def restore_revision(self, connector_id: str, version: int) -> dict:
+        """Copy a published version back into the draft, returning the draft.
+
+        Does not publish: the restored config becomes the connector's draft and
+        needs an explicit publish to go live.
+        """
         with self._client() as c:
-            r = c.post(self._url(f"/connectors/{connector_id}/revisions/{version}/restore"))
+            r = c.post(self._url(f"/connectors/{connector_id}/versions/{version}/restore"))
             r.raise_for_status()
             return r.json()
 

plugsync_cli/commands/auth.py

@@ -125,6 +125,10 @@ def auth_login(email: str | None, password: str | None, token: str | None):
         raise SystemExit(1)
     except httpx.RequestError as exc:
         console.print(f"[red]Could not reach {api_url}: {exc}[/red]")
+        console.print(
+            "[yellow]Is this the right API URL? Set it with "
+            "'plugsync config set api_url <url>'.[/yellow]"
+        )
         raise SystemExit(1)
 
     data = response.json()

plugsync_cli/commands/diff.py

@@ -1,169 +1,122 @@
-"""plugsync diff — compare local files vs published revision (read-only)."""
-from __future__ import annotations
-
-import io
+"""plugsync diff -- compare local files against a published version (read-only).
+
+Two bugs made this command report "no changes" no matter what (#1241). It read
+the published side through `export_revision`, an endpoint Plan 6a deleted, and
+it read the local side by packing the directory into a zip whose entries are
+prefixed with the connector name while matching them at the root of the
+archive -- so the local state was always empty, and an empty local state
+diffs clean against anything. Both sides now compare config blobs directly:
+the local directory as `serializer.read_config_directory` returns it, the
+published one as `GET /versions/{v}` returns it. No zip in between.
+"""
 import json
-import zipfile
-from pathlib import Path
 
 import click
-import yaml
 from rich.console import Console
 from rich.table import Table
 
-from plugsync_cli.client import PlugSyncClient
-from plugsync_cli.serializer import read_directory_to_zip
+from plugsync_cli.context import build_client, fail, load_context
 
 console = Console()
 
+# Top-level config keys compared item-by-item (keyed by name) rather than whole.
+COLLECTIONS = {"entities": "entity", "flows": "flow"}
 
-def _resolve_context(path: str | None) -> tuple[Path, str]:
-    """Resolve connector dir and connector_id."""
-    connector_dir = Path(path) if path else Path.cwd()
-    if not (connector_dir / "plugsync.yaml").exists():
-        console.print("[red]No plugsync.yaml found. Run from a connector directory or specify path.[/red]")
-        raise SystemExit(1)
 
-    local_config = connector_dir / ".plugsync.yaml"
-    if not local_config.exists():
-        console.print("[red]No .plugsync.yaml found. Run 'plugsync pull' first.[/red]")
-        raise SystemExit(1)
+def _by_name(items) -> dict[str, dict]:
+    return {item["name"]: item for item in items or []}
 
-    with open(local_config) as f:
-        data = yaml.safe_load(f) or {}
-    connector_id = data.get("connector_id")
-    if not connector_id:
-        console.print("[red]No connector_id in .plugsync.yaml[/red]")
-        raise SystemExit(1)
 
-    return connector_dir, connector_id
+def _differs(left, right) -> bool:
+    return json.dumps(left, sort_keys=True) != json.dumps(right, sort_keys=True)
 
 
-def _read_zip_contents(zip_data: bytes) -> dict:
-    """Extract settings, entities, and handlers from a connector zip."""
-    settings: dict = {}
-    entities: dict[str, dict] = {}
-    handlers: dict[str, str] = {}
+def _diff_configs(local: dict, remote: dict) -> list[dict]:
+    """Changes that turn `remote` into `local`, one row per named item or key."""
+    changes: list[dict] = []
 
-    with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
-        for name in zf.namelist():
-            if name == "plugsync.yaml" or name == "settings.yaml":
-                raw = yaml.safe_load(zf.read(name)) or {}
-                settings = raw
-            elif name.startswith("entities/") and name.endswith(".yaml"):
-                entity_name = Path(name).stem
-                entities[entity_name] = yaml.safe_load(zf.read(name)) or {}
-            elif name.startswith("handlers/") and name.endswith(".py"):
-                handler_name = Path(name).stem
-                handlers[handler_name] = zf.read(name).decode()
+    for key, label in COLLECTIONS.items():
+        local_items, remote_items = _by_name(local.get(key)), _by_name(remote.get(key))
+        for name in sorted(set(local_items) | set(remote_items)):
+            if name not in remote_items:
+                changes.append({"type": f"{label}_added", "scope": name, "detail": "only in local files"})
+            elif name not in local_items:
+                changes.append({"type": f"{label}_removed", "scope": name, "detail": "only in the published version"})
+            elif _differs(local_items[name], remote_items[name]):
+                changes.append({"type": f"{label}_modified", "scope": name, "detail": "differs"})
+
+    scalar_keys = (set(local) | set(remote)) - set(COLLECTIONS)
+    for key in sorted(scalar_keys):
+        if _differs(local.get(key), remote.get(key)):
+            changes.append({"type": f"{key}_modified", "scope": key, "detail": "differs"})
 
-    return {"settings": settings, "entities": entities, "handlers": handlers}
+    return changes
 
 
-def _diff_states(local: dict, remote: dict) -> list[dict]:
-    """Compare local and remote states, return list of changes."""
-    changes: list[dict] = []
+def _local_item_count(config: dict) -> int:
+    collections = sum(len(config.get(key) or []) for key in COLLECTIONS)
+    scalars = sum(1 for key, value in config.items() if key not in COLLECTIONS and value)
+    return collections + scalars
 
-    # Settings
-    if json.dumps(local["settings"], sort_keys=True) != json.dumps(remote["settings"], sort_keys=True):
-        changes.append({"type": "settings_modified", "detail": "Settings changed", "entity": "", "handler": ""})
-
-    # Entities
-    all_entities = set(local["entities"].keys()) | set(remote["entities"].keys())
-    for name in sorted(all_entities):
-        if name in local["entities"] and name not in remote["entities"]:
-            changes.append({"type": "entity_added", "detail": f"Entity '{name}' added", "entity": name, "handler": ""})
-        elif name not in local["entities"] and name in remote["entities"]:
-            changes.append({"type": "entity_removed", "detail": f"Entity '{name}' removed", "entity": name, "handler": ""})
-        else:
-            if json.dumps(local["entities"][name], sort_keys=True) != json.dumps(remote["entities"][name], sort_keys=True):
-                changes.append({"type": "entity_modified", "detail": f"Entity '{name}' modified", "entity": name, "handler": ""})
-
-    # Handlers
-    all_handlers = set(local["handlers"].keys()) | set(remote["handlers"].keys())
-    for name in sorted(all_handlers):
-        if name in local["handlers"] and name not in remote["handlers"]:
-            changes.append({"type": "handler_added", "detail": f"Handler '{name}' added", "entity": "", "handler": name})
-        elif name not in local["handlers"] and name in remote["handlers"]:
-            changes.append({"type": "handler_removed", "detail": f"Handler '{name}' removed", "entity": "", "handler": name})
-        else:
-            if local["handlers"][name] != remote["handlers"][name]:
-                changes.append({"type": "handler_modified", "detail": f"Handler '{name}' modified", "entity": "", "handler": name})
 
-    return changes
+def _render(changes: list[dict]) -> None:
+    console.print(f"\n[bold]{len(changes)} change{'' if len(changes) == 1 else 's'} detected[/bold]\n")
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Change", width=24)
+    table.add_column("Item")
+    table.add_column("Detail")
+    for change in changes:
+        change_type = change["type"]
+        if change_type.endswith("_added"):
+            rendered = f"[green]+ {change_type}[/green]"
+        elif change_type.endswith("_removed"):
+            rendered = f"[red]- {change_type}[/red]"
+        else:
+            rendered = f"[yellow]~ {change_type}[/yellow]"
+        table.add_row(rendered, change["scope"], change["detail"])
+    console.print(table)
 
 
 @click.command()
 @click.argument("path", required=False, default=None)
-def diff(path: str | None):
-    """Show what changed between local files and published revision.
-
-    Compares local files against the remote published state WITHOUT
-    uploading anything. This is a read-only operation.
+@click.option(
+    "--revision",
+    "-r",
+    type=int,
+    default=None,
+    help="Compare against a specific published version (default: the newest)",
+)
+def diff(path: str | None, revision: int | None):
+    """Show what differs between local files and a published version.
+
+    Read-only: nothing is uploaded. To see what a publish would change instead,
+    use `plugsync preview`, which diffs the DRAFT against the active version.
 
     Examples:
         plugsync diff
         plugsync diff ./hubspot-juve
+        plugsync diff --revision 3
     """
-    try:
-        client = PlugSyncClient()
-    except RuntimeError as e:
-        console.print(f"[red]{e}[/red]")
-        raise SystemExit(1)
-
-    connector_dir, connector_id = _resolve_context(path)
-
-    # Read local files into a zip and parse them
-    local_zip = read_directory_to_zip(connector_dir)
-    local_state = _read_zip_contents(local_zip)
-
-    # Get the latest revision number from remote
-    revisions = client.list_revisions(connector_id)
-    if not revisions:
-        console.print("[yellow]No published revisions yet. Everything is new.[/yellow]")
-        n = len(local_state["entities"]) + len(local_state["handlers"])
-        if local_state["settings"]:
-            n += 1
-        console.print(f"[bold]{n} local item(s) would be published.[/bold]")
-        return
-
-    latest_version = revisions[0]["version"]
-    remote_zip = client.export_revision(connector_id, latest_version)
-    remote_state = _read_zip_contents(remote_zip)
-
-    changes = _diff_states(local_state, remote_state)
-
+    client = build_client()
+    context = load_context(path)
+    local_config = context.config()
+
+    if revision is None:
+        versions = client.list_revisions(context.connector_id)
+        if not versions:
+            console.print("[yellow]No published versions yet. Everything is new.[/yellow]")
+            count = _local_item_count(local_config)
+            console.print(f"[bold]{count} local item(s) would be published.[/bold]")
+            return
+        revision = versions[0]["version"]
+
+    remote_config = client.get_version(context.connector_id, revision)["config"]
+    if not isinstance(remote_config, dict):
+        fail(f"Version {revision} carries no readable config.")
+
+    console.print(f"Comparing local files against published v{revision}...")
+    changes = _diff_configs(local_config, remote_config)
     if not changes:
-        console.print("[green]No changes. Local files match published revision.[/green]")
+        console.print(f"[green]No changes. Local files match published v{revision}.[/green]")
         return
-
-    summary = f"{len(changes)} change{'s' if len(changes) != 1 else ''} detected"
-    console.print(f"\n[bold]{summary}[/bold]\n")
-
-    table = Table(show_header=True, header_style="bold")
-    table.add_column("Type", style="cyan", width=20)
-    table.add_column("Detail")
-
-    for change in changes:
-        change_type = change.get("type", "unknown")
-        detail = change.get("detail", "")
-        entity = change.get("entity", "")
-        handler = change.get("handler", "")
-
-        label = entity or handler or ""
-        if label:
-            detail = f"[bold]{label}[/bold]: {detail}"
-
-        # Color by type
-        if "added" in change_type:
-            type_style = "[green]+ added[/green]"
-        elif "removed" in change_type:
-            type_style = "[red]- removed[/red]"
-        elif "modified" in change_type:
-            type_style = "[yellow]~ modified[/yellow]"
-        else:
-            type_style = change_type
-
-        table.add_row(type_style, detail)
-
-    console.print(table)
+    _render(changes)

plugsync_cli/commands/preview.py

@@ -1,107 +1,68 @@
-"""plugsync preview — preview changes with simulation."""
-from pathlib import Path
-
+"""plugsync preview -- what publishing the draft would change."""
 import click
-import yaml
 from rich.console import Console
-from rich.panel import Panel
 from rich.table import Table
 
-from plugsync_cli.client import PlugSyncClient
-from plugsync_cli.serializer import read_directory_to_zip
+from plugsync_cli.context import (
+    build_client,
+    load_context,
+    warn_if_local_differs_from_draft,
+)
+from plugsync_cli.findings import render_preflight
 
 console = Console()
 
+# Rendering per change type, keyed by the verb the backend's ChangeDetail uses.
+_CHANGE_MARKS = (("added", "+", "green"), ("removed", "-", "red"), ("modified", "~", "yellow"))
+
+
+def _mark(change_type: str) -> str:
+    for verb, glyph, colour in _CHANGE_MARKS:
+        if verb in change_type:
+            return f"[{colour}]{glyph} {change_type}[/{colour}]"
+    return change_type
+
 
 @click.command()
 @click.argument("path", required=False, default=None)
 def preview(path: str | None):
-    """Preview what would change if you publish now.
+    """Preview the diff a publish would apply, plus its preflight findings.
+
+    Read-only: this uploads nothing and publishes nothing. Both halves are
+    server-side views of the DRAFT (`GET /preview` for the diff against the
+    active version, `GET /preflight` for the findings), so the command warns
+    when the local files differ from the draft it is describing.
 
-    Uploads local state, diffs against published revision,
-    and shows a simulation of the effect.
+    Always exits 0, findings included: preflight is advisory and never gates a
+    publish. Use `plugsync validate` when you want errors to fail a pipeline.
 
     Examples:
         plugsync preview
         plugsync preview ./hubspot-juve
     """
-    try:
-        client = PlugSyncClient()
-    except RuntimeError as e:
-        console.print(f"[red]{e}[/red]")
-        raise SystemExit(1)
+    client = build_client()
+    context = load_context(path)
 
-    connector_dir = Path(path) if path else Path.cwd()
-    if not (connector_dir / "plugsync.yaml").exists():
-        console.print("[red]No plugsync.yaml found.[/red]")
-        raise SystemExit(1)
-
-    local_config = connector_dir / ".plugsync.yaml"
-    if not local_config.exists():
-        console.print("[red]No .plugsync.yaml found. Run 'plugsync pull' first.[/red]")
-        raise SystemExit(1)
-
-    with open(local_config) as f:
-        data = yaml.safe_load(f) or {}
-    connector_id = data.get("connector_id")
-
-    # Upload current state (required for server-side preview)
-    zip_data = read_directory_to_zip(connector_dir)
-    click.confirm(
-        "This will upload your local files to the remote working state. Continue?",
-        abort=True,
+    warn_if_local_differs_from_draft(
+        context.config(), client.get_draft(context.connector_id)["config"]
     )
-    client.import_zip(connector_id, zip_data)
-
-    # Preview
-    result = client.preview(connector_id)
-
-    changes = result.get("changes", [])
-    warnings = result.get("warnings", [])
-    simulation = result.get("simulation")
-    summary = result.get("summary", "0 changes")
 
+    result = client.preview(context.connector_id)
+    changes = result.get("changes") or []
     if not changes:
-        console.print("[green]No changes to publish.[/green]")
-        return
-
-    # Changes table
-    console.print(f"\n[bold]Preview: {summary}[/bold]\n")
-
-    table = Table(show_header=True, header_style="bold")
-    table.add_column("Change", width=20)
-    table.add_column("Detail")
-
-    for change in changes:
-        change_type = change.get("type", "unknown")
-        detail = change.get("detail", "")
-
-        if "added" in change_type:
-            prefix = "[green]+[/green]"
-        elif "removed" in change_type:
-            prefix = "[red]-[/red]"
-        elif "modified" in change_type:
-            prefix = "[yellow]~[/yellow]"
-        else:
-            prefix = " "
-
-        table.add_row(f"{prefix} {change_type}", detail)
-
-    console.print(table)
-
-    # Simulation
-    if simulation:
-        import json
-        console.print(Panel(
-            json.dumps(simulation, indent=2),
-            title="Simulation",
-            border_style="blue",
-        ))
-
-    # Warnings
-    if warnings:
-        console.print("\n[yellow]Warnings:[/yellow]")
-        for w in warnings:
-            console.print(f"  [yellow]! {w.get('detail', '')}[/yellow]")
-
-    console.print(f"\nRun [bold]plugsync push[/bold] to publish these changes.")
+        console.print("[green]No changes to publish: the draft matches the active version.[/green]")
+    else:
+        console.print(f"\n[bold]Publishing would apply {len(changes)} change(s)[/bold]\n")
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("Change", width=24)
+        table.add_column("Detail")
+        for change in changes:
+            scope = change.get("entity") or change.get("event_flow") or ""
+            detail = change.get("detail", "")
+            table.add_row(_mark(change.get("type", "unknown")), f"[bold]{scope}[/bold] {detail}" if scope else detail)
+        console.print(table)
+
+    render_preflight(console, client.preflight(context.connector_id))
+
+    if changes:
+        console.print("\nRun [bold]plugsync push --publish[/bold] to apply them.")