plugsync-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{plugsync_cli-0.1.0 → plugsync_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: Command-line client for plugsync HubSpot connectors -- manage connectors and plugins like code, no repo checkout required
 Author-email: Exelab <hello@plugsync.com>
 License: Proprietary
@@ -33,8 +33,12 @@ Requires-Dist: respx>=0.21; extra == "dev"
 
 Command-line client for [plugsync](https://plugsync.com), managing HubSpot
 connectors like code: pull a connector's config to a local directory, edit
-it, push it back, diff against the remote, validate, preview a publish, and
-manage plugins -- all without cloning the plugsync backend repo.
+it, push it back to the draft, diff against a published version, validate,
+preview a publish, and manage plugins -- all without cloning the plugsync
+backend repo.
+
+`push` writes the draft and stops. Publishing is opt-in (`push --publish`),
+so a config never reaches production as a side effect of saving a file.
 
 ## Install
 
@@ -47,14 +51,16 @@ Requires Python 3.12+.
 ## Quickstart
 
 ```bash
-plugsync config set api_url https://your-plugsync-instance.example.com
 plugsync auth login -e you@example.com
 plugsync pull my-connector
 ```
 
-`plugsync auth login` saves a bearer credential to `~/.plugsync/config.yaml`
-that every subsequent command reuses. `PLUGSYNC_API_URL` / `PLUGSYNC_API_KEY`
-environment variables override the config file, handy for CI.
+`api_url` defaults to the hosted platform (`https://app.plugsync.com`), so
+there's nothing to configure for the common case. Point it elsewhere with
+`plugsync config set api_url <url>`. `plugsync auth login` saves a bearer
+credential to `~/.plugsync/config.yaml` that every subsequent command
+reuses. `PLUGSYNC_API_URL` / `PLUGSYNC_API_KEY` environment variables
+override the config file, handy for CI.
 
 ## Commands
 
@@ -62,14 +68,14 @@ environment variables override the config file, handy for CI.
 |---|---|
 | `plugsync auth login` / `logout` | Authenticate (email/password JWT, or a long-lived org API key with `--token`) |
 | `plugsync config set/get/show` | Manage `~/.plugsync/config.yaml` |
-| `plugsync pull <name>` | Download a connector as a local directory |
-| `plugsync push <name>` | Upload a local connector directory |
-| `plugsync diff <name>` | Diff local vs. remote working state |
-| `plugsync validate <name>` | Validate a local connector config |
-| `plugsync preview <name>` | Preview a publish's effects |
-| `plugsync log <name>` | Show a connector's revision history |
-| `plugsync rollback <name>` | Restore a previous revision |
-| `plugsync plugin init/push/list/status/logs/invoke` | Author and manage plugins (Enterprise tier) |
+| `plugsync pull <name>` | Download a connector's draft as a local directory (`--revision N` for a published version) |
+| `plugsync push <name>` | Upload a local connector directory to the draft (`--publish` to also publish) |
+| `plugsync diff <name>` | Diff local files vs. a published version |
+| `plugsync validate <name>` | Preflight the draft; non-zero exit on an error |
+| `plugsync preview <name>` | Preview a publish's effects and its preflight findings |
+| `plugsync log <name>` | Show a connector's published version history |
+| `plugsync rollback <name>` | Restore a published version into the draft |
+| `plugsync plugin init/push/list/status/logs/metrics/invoke/promote/publish/rollback` | Author and manage plugins (Enterprise tier) |
 
 Run `plugsync --help` or `plugsync <command> --help` for the full option list.
 
@@ -83,7 +89,7 @@ against the API at the start of any command that talks to it, warning
 ## Documentation
 
 Full reference docs, including the plugin authoring dev-loop, live at
-[docs.plugsync.com](https://plugsync.com) and in the
+[docs.plugsync.com](https://docs.plugsync.com) and in the
 [plugsync repository](https://github.com/exelab/plugsync/tree/main/docs).
 
 ## License

plugsync_cli-0.3.0/README.md

@@ -0,0 +1,68 @@
+# plugsync-cli
+
+Command-line client for [plugsync](https://plugsync.com), managing HubSpot
+connectors like code: pull a connector's config to a local directory, edit
+it, push it back to the draft, diff against a published version, validate,
+preview a publish, and manage plugins -- all without cloning the plugsync
+backend repo.
+
+`push` writes the draft and stops. Publishing is opt-in (`push --publish`),
+so a config never reaches production as a side effect of saving a file.
+
+## Install
+
+```bash
+pip install plugsync-cli
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```bash
+plugsync auth login -e you@example.com
+plugsync pull my-connector
+```
+
+`api_url` defaults to the hosted platform (`https://app.plugsync.com`), so
+there's nothing to configure for the common case. Point it elsewhere with
+`plugsync config set api_url <url>`. `plugsync auth login` saves a bearer
+credential to `~/.plugsync/config.yaml` that every subsequent command
+reuses. `PLUGSYNC_API_URL` / `PLUGSYNC_API_KEY` environment variables
+override the config file, handy for CI.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `plugsync auth login` / `logout` | Authenticate (email/password JWT, or a long-lived org API key with `--token`) |
+| `plugsync config set/get/show` | Manage `~/.plugsync/config.yaml` |
+| `plugsync pull <name>` | Download a connector's draft as a local directory (`--revision N` for a published version) |
+| `plugsync push <name>` | Upload a local connector directory to the draft (`--publish` to also publish) |
+| `plugsync diff <name>` | Diff local files vs. a published version |
+| `plugsync validate <name>` | Preflight the draft; non-zero exit on an error |
+| `plugsync preview <name>` | Preview a publish's effects and its preflight findings |
+| `plugsync log <name>` | Show a connector's published version history |
+| `plugsync rollback <name>` | Restore a published version into the draft |
+| `plugsync plugin init/push/list/status/logs/metrics/invoke/promote/publish/rollback` | Author and manage plugins (Enterprise tier) |
+
+Run `plugsync --help` or `plugsync <command> --help` for the full option list.
+
+## Compatibility
+
+This CLI ships on its own release cadence, independent of the plugsync
+backend. It declares the minimum API version it expects and checks it
+against the API at the start of any command that talks to it, warning
+(never failing outright) if the API is older than expected.
+
+## Documentation
+
+Full reference docs, including the plugin authoring dev-loop, live at
+[docs.plugsync.com](https://docs.plugsync.com) and in the
+[plugsync repository](https://github.com/exelab/plugsync/tree/main/docs).
+
+## License
+
+Proprietary. This CLI talks to the plugsync SaaS API; see
+[plugsync.com/terms](https://plugsync.com/terms) for the terms governing use
+of the plugsync service.

{plugsync_cli-0.1.0 → plugsync_cli-0.3.0}/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-0.1.0 → plugsync_cli-0.3.0}/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-0.3.0/plugsync_cli/commands/diff.py

@@ -0,0 +1,122 @@
+"""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 click
+from rich.console import Console
+from rich.table import Table
+
+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 _by_name(items) -> dict[str, dict]:
+    return {item["name"]: item for item in items or []}
+
+
+def _differs(left, right) -> bool:
+    return json.dumps(left, sort_keys=True) != json.dumps(right, sort_keys=True)
+
+
+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] = []
+
+    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 changes
+
+
+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
+
+
+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)
+@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
+    """
+    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(f"[green]No changes. Local files match published v{revision}.[/green]")
+        return
+    _render(changes)

plugsync_cli-0.3.0/plugsync_cli/commands/preview.py

@@ -0,0 +1,68 @@
+"""plugsync preview -- what publishing the draft would change."""
+import click
+from rich.console import Console
+from rich.table import Table
+
+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 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.
+
+    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
+    """
+    client = build_client()
+    context = load_context(path)
+
+    warn_if_local_differs_from_draft(
+        context.config(), client.get_draft(context.connector_id)["config"]
+    )
+
+    result = client.preview(context.connector_id)
+    changes = result.get("changes") or []
+    if not 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.")

plugsync_cli-0.3.0/plugsync_cli/commands/pull.py

@@ -0,0 +1,70 @@
+"""plugsync pull -- download a connector's config into a local directory."""
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from plugsync_cli.context import build_client, fail, warn_if_flow_order_is_not_preserved
+from plugsync_cli.serializer import write_config_directory, write_local_state
+
+console = Console()
+
+
+@click.command()
+@click.argument("connector_name")
+@click.option(
+    "--revision",
+    "-r",
+    type=int,
+    default=None,
+    help="Pull a published version instead of the draft",
+)
+@click.option("--output", "-o", type=click.Path(), default=None, help="Output directory path")
+def pull(connector_name: str, revision: int | None, output: str | None):
+    """Download a connector's config as a local directory.
+
+    Without --revision this reads the DRAFT (the editable config, what the
+    dashboard shows under "Review changes"). With --revision it reads a
+    published version, which is read-only history.
+
+    Examples:
+        plugsync pull hubspot-juve
+        plugsync pull hubspot-juve --revision 3
+        plugsync pull hubspot-juve -o ./my-dir
+    """
+    client = build_client()
+
+    connector = client.find_connector(connector_name)
+    if not connector:
+        fail(f"Connector '{connector_name}' not found")
+    connector_id = connector["id"]
+
+    state = {"connector": connector_name, "connector_id": connector_id}
+    if revision is not None:
+        console.print(f"Pulling v{revision} of [bold]{connector_name}[/bold]...")
+        payload = client.get_version(connector_id, revision)
+        state["source"] = f"version {revision}"
+        state["version"] = payload["version"]
+    else:
+        console.print(f"Pulling the draft of [bold]{connector_name}[/bold]...")
+        payload = client.get_draft(connector_id)
+        state["source"] = "draft"
+        # Recorded so `push` can send it as its expected_version: that is what
+        # turns a concurrent dashboard edit into a 409 instead of a silent
+        # overwrite of someone else's work.
+        state["draft_version"] = payload["draft_version"]
+
+    config = payload["config"]
+    output_dir = Path(output) if output else Path.cwd() / connector_name
+    write_config_directory(output_dir, config)
+    write_local_state(output_dir, state)
+
+    warn_if_flow_order_is_not_preserved(config)
+
+    entities = len(config.get("entities") or [])
+    flows = len(config.get("flows") or [])
+    console.print(f"[green]Pulled {state['source']} to {output_dir}/[/green]")
+    console.print(
+        f"  {entities} entit{'y' if entities == 1 else 'ies'}, "
+        f"{flows} flow{'' if flows == 1 else 's'}"
+    )