plugsync-cli 0.1.0__tar.gz

plugsync_cli-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: plugsync-cli
+Version: 0.1.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
+Project-URL: Homepage, https://plugsync.com
+Project-URL: Documentation, https://github.com/exelab/plugsync/blob/main/docs/content/reference/plugins/dev-loop.md
+Project-URL: Repository, https://github.com/exelab/plugsync
+Project-URL: Issues, https://github.com/exelab/plugsync/issues
+Keywords: plugsync,hubspot,cli,connectors,integration
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# 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, diff against the remote, validate, preview a publish, and
+manage plugins -- all without cloning the plugsync backend repo.
+
+## Install
+
+```bash
+pip install plugsync-cli
+```
+
+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.
+
+## 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 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) |
+
+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://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/README.md

@@ -0,0 +1,62 @@
+# 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, diff against the remote, validate, preview a publish, and
+manage plugins -- all without cloning the plugsync backend repo.
+
+## Install
+
+```bash
+pip install plugsync-cli
+```
+
+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.
+
+## 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 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) |
+
+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://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/__init__.py

@@ -0,0 +1,2 @@
+"""PluSync CLI — git-like connector management."""
+__version__ = "0.1.0"

plugsync_cli-0.1.0/plugsync_cli/bundler.py

@@ -0,0 +1,77 @@
+"""Bundle a TypeScript plugin directory into a single JS bundle via esbuild.
+
+esbuild must be available on PATH (installed via `npm install -g esbuild` or
+as a devDependency in the plugin directory).
+
+Returns (bundle_bytes, sha256_hexdigest).
+"""
+import hashlib
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def bundle_plugin(src_dir: str | Path) -> tuple[bytes, str]:
+    """Bundle the TypeScript entrypoint in *src_dir* using esbuild.
+
+    Expects ``src_dir/src/index.ts`` as the entrypoint.  The bundle is
+    written to a temporary file, read back as bytes, and its SHA-256 digest
+    is computed before returning.
+
+    Raises ``RuntimeError`` when esbuild fails or is not found.
+    """
+    src_dir = Path(src_dir)
+    entrypoint = src_dir / "src" / "index.ts"
+    if not entrypoint.exists():
+        raise RuntimeError(
+            f"Entrypoint not found: {entrypoint}. "
+            "Expected src/index.ts in the plugin directory."
+        )
+
+    with tempfile.NamedTemporaryFile(suffix=".js", delete=False) as tmp:
+        out_path = tmp.name
+
+    cmd = [
+        "esbuild",
+        str(entrypoint),
+        "--bundle",
+        "--platform=node",
+        "--target=node18",
+        "--format=cjs",
+        f"--outfile={out_path}",
+    ]
+
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        raise RuntimeError(
+            "esbuild not found. Install it with: npm install -g esbuild"
+        ) from None
+
+    if proc.returncode != 0:
+        try:
+            os.unlink(out_path)
+        except OSError:
+            # Best-effort temp file cleanup; ignore errors so the real error is raised
+            pass
+        raise RuntimeError(
+            f"esbuild failed (exit {proc.returncode}):\n{proc.stderr}"
+        )
+
+    try:
+        bundle_bytes = Path(out_path).read_bytes()
+        digest = hashlib.sha256(bundle_bytes).hexdigest()
+    finally:
+        try:
+            os.unlink(out_path)
+        except OSError:
+            # Best-effort temp file cleanup on success or read failure; ignore errors
+            pass
+
+    return bundle_bytes, digest

plugsync_cli-0.1.0/plugsync_cli/client.py

@@ -0,0 +1,201 @@
+"""HTTP client wrapper for PluSync REST API."""
+import httpx
+
+from plugsync_cli.compat import check_api_compat
+from plugsync_cli.config import get_api_key, get_api_url
+
+
+class PlugSyncClient:
+    """Thin wrapper around httpx for PluSync API calls."""
+
+    def __init__(self, api_url: str | None = None, api_key: str | None = None):
+        self.api_url = api_url or get_api_url()
+        self.api_key = api_key or get_api_key()
+        if not self.api_key:
+            raise RuntimeError(
+                "No API key configured. Run 'plugsync config set api_key <key>' "
+                "or set PLUGSYNC_API_KEY environment variable."
+            )
+        try:
+            check_api_compat(self.api_url)
+        except Exception:
+            # Compat check is advisory only (issue #957): never let it
+            # block a command from running, even if it misbehaves.
+            pass
+        self.headers = {"Authorization": f"Bearer {self.api_key}"}
+
+    def _url(self, path: str) -> str:
+        return f"{self.api_url}/api{path}"
+
+    def _client(self) -> httpx.Client:
+        return httpx.Client(headers=self.headers, timeout=60.0)
+
+    def list_connectors(self) -> list[dict]:
+        with self._client() as c:
+            r = c.get(self._url("/connectors"))
+            r.raise_for_status()
+            return r.json()
+
+    def find_connector(self, name: str) -> dict | None:
+        connectors = self.list_connectors()
+        for conn in connectors:
+            if conn["name"] == name:
+                return conn
+        return None
+
+    def get_connector(self, connector_id: str) -> dict:
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}"))
+            r.raise_for_status()
+            return r.json()
+
+    def export_working_state(self, connector_id: str) -> bytes:
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/export"))
+            r.raise_for_status()
+            return r.content
+
+    def export_revision(self, connector_id: str, version: int) -> bytes:
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/revisions/{version}/export"))
+            r.raise_for_status()
+            return r.content
+
+    def import_zip(self, connector_id: str, zip_data: bytes) -> dict:
+        with self._client() as c:
+            r = c.post(
+                self._url(f"/connectors/{connector_id}/import"),
+                files={"file": ("connector.zip", zip_data, "application/zip")},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def validate(self, connector_id: str) -> dict:
+        with self._client() as c:
+            r = c.post(self._url(f"/connectors/{connector_id}/validate"))
+            r.raise_for_status()
+            return r.json()
+
+    def preview(self, connector_id: str) -> dict:
+        with self._client() as c:
+            r = c.post(self._url(f"/connectors/{connector_id}/preview"))
+            r.raise_for_status()
+            return r.json()
+
+    def publish(self, connector_id: str, change_summary: str | None = None) -> dict:
+        with self._client() as c:
+            body = {}
+            if change_summary:
+                body["change_summary"] = change_summary
+            r = c.post(self._url(f"/connectors/{connector_id}/publish"), json=body)
+            r.raise_for_status()
+            return r.json()
+
+    def list_revisions(self, connector_id: str) -> list[dict]:
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/revisions"))
+            r.raise_for_status()
+            return r.json()
+
+    def restore_revision(self, connector_id: str, version: int) -> dict:
+        with self._client() as c:
+            r = c.post(self._url(f"/connectors/{connector_id}/revisions/{version}/restore"))
+            r.raise_for_status()
+            return r.json()
+
+    # ------------------------------------------------------------------
+    # Plugin API (T10, issue #190)
+    # ------------------------------------------------------------------
+
+    def plugin_create(self, name: str, capabilities: list[str] | None = None) -> dict:
+        """Create a new plugin (status=draft)."""
+        body: dict = {"name": name}
+        if capabilities is not None:
+            body["capabilities"] = capabilities
+        with self._client() as c:
+            r = c.post(self._url("/plugins"), json=body)
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_list(self) -> list[dict]:
+        """List all plugins for the current org."""
+        with self._client() as c:
+            r = c.get(self._url("/plugins"))
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_get(self, plugin_id: str) -> dict:
+        """Get a single plugin by ID."""
+        with self._client() as c:
+            r = c.get(self._url(f"/plugins/{plugin_id}"))
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_push(self, plugin_id: str, bundle_bytes: bytes, source_code: str) -> dict:
+        """Upload a new bundle + source_code for a plugin (multipart/form-data)."""
+        with self._client() as c:
+            r = c.post(
+                self._url(f"/plugins/{plugin_id}/push"),
+                files={"bundle": ("plugin.js", bundle_bytes, "application/javascript")},
+                data={"source_code": source_code},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_promote(self, plugin_id: str, target: str) -> dict:
+        """Promote a plugin to staging or live."""
+        with self._client() as c:
+            r = c.post(
+                self._url(f"/plugins/{plugin_id}/promote"),
+                json={"target": target},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_invoke(self, plugin_id: str, payload: dict) -> dict:
+        """Proxy an invocation to the plugin's Lambda function."""
+        with self._client() as c:
+            r = c.post(
+                self._url(f"/plugins/{plugin_id}/invoke"),
+                json={"payload": payload},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_logs(
+        self,
+        plugin_id: str,
+        connector_id: str | None = None,
+        since_minutes: int | None = None,
+        limit: int | None = None,
+    ) -> dict:
+        """Tail the most recent CloudWatch log lines for a plugin.
+
+        Optional filters (#293): connector_id narrows to one connector's
+        lines, since_minutes widens the lookback, limit caps the line count.
+        """
+        params: dict = {}
+        if connector_id is not None:
+            params["connector_id"] = connector_id
+        if since_minutes is not None:
+            params["since_minutes"] = since_minutes
+        if limit is not None:
+            params["limit"] = limit
+        with self._client() as c:
+            r = c.get(self._url(f"/plugins/{plugin_id}/logs"), params=params)
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_metrics(self, plugin_id: str, window: str = "24h") -> dict:
+        """CloudWatch metrics (invocations, errors, latency) for a plugin (#293)."""
+        with self._client() as c:
+            r = c.get(
+                self._url(f"/plugins/{plugin_id}/metrics"),
+                params={"window": window},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_status(self, plugin_id: str) -> dict:
+        """Get the current status of a plugin."""
+        return self.plugin_get(plugin_id)

plugsync_cli-0.1.0/plugsync_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands."""

plugsync_cli-0.1.0/plugsync_cli/commands/auth.py

@@ -0,0 +1,156 @@
+"""plugsync auth -- authentication helpers (T10, issue #190; issue #725).
+
+Two ways to authenticate:
+
+- Email + password login (``plugsync auth login``): exchanges credentials
+  for a short-TTL JWT (15 min), saved as the bearer credential (api_key) in
+  ~/.plugsync/config.yaml. Fine for interactive use; a long-running script
+  will eventually hit a 401 once the JWT lapses (see the refresh recipe in
+  the API-first quickstart for that case).
+- Org API key (``plugsync auth login --token ps_org_...``): saves an
+  existing org-level API key as-is, no login round-trip. This is the
+  recommended path for CI/scripts -- an org key has no forced 15-minute
+  expiry (only an optional ``expires_at`` set at creation time), so a
+  session built on it survives for hours without any refresh dance.
+
+``PLUGSYNC_API_KEY`` overrides whatever is saved in config.yaml for either
+credential type, without touching the file on disk -- handy for CI secrets.
+
+OAuth device-flow is a post-Phase-A follow-up.
+"""
+import httpx
+import click
+from rich.console import Console
+
+from plugsync_cli.config import get_api_url, get_config, save_config
+
+console = Console()
+
+
+def _save_api_key(value: str) -> None:
+    """Persist ``value`` as the bearer credential in ~/.plugsync/config.yaml."""
+    cfg = get_config()
+    cfg["api_key"] = value
+    save_config(cfg)
+
+
+@click.group("auth")
+def auth():
+    """Authenticate with plugsync."""
+    pass
+
+
+@auth.command("login")
+@click.option("--email", "-e", default=None, help="Email address")
+@click.option("--password", "-p", default=None, help="Password", hide_input=True)
+@click.option(
+    "--token",
+    "-t",
+    default=None,
+    help="Org API key (ps_org_...) to save directly, skipping email/password login. "
+    "Recommended for CI/scripts (issue #725): no forced 15-minute expiry.",
+)
+def auth_login(email: str | None, password: str | None, token: str | None):
+    """Log in and save credentials for subsequent commands.
+
+    Two modes:
+
+    \b
+    - `plugsync auth login --token ps_org_...`: saves an existing org API
+      key as-is. No network call, no email/password prompt.
+    - `plugsync auth login` (or with -e/-p): prompts for email and password
+      if not supplied, exchanges them for a short-TTL JWT, and saves that.
+
+    The credential is saved under api_key in ~/.plugsync/config.yaml.
+
+    Example:
+        plugsync auth login --token ps_org_abc123...
+        plugsync auth login
+        plugsync auth login -e you@example.com
+    """
+    if token:
+        if not token.startswith("ps_org_"):
+            console.print(
+                "[yellow]Warning: this doesn't look like an org API key "
+                "(expected prefix 'ps_org_'). Saving it anyway.[/yellow]"
+            )
+        _save_api_key(token)
+        console.print("[green]Org API key saved to ~/.plugsync/config.yaml[/green]")
+        return
+
+    if not email:
+        email = click.prompt("Email")
+    if not password:
+        password = click.prompt("Password", hide_input=True)
+
+    api_url = get_api_url()
+    login_url = f"{api_url}/api/auth/login"
+
+    try:
+        response = httpx.post(
+            login_url,
+            json={"email": email, "password": password},
+            timeout=30.0,
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code
+        try:
+            detail = exc.response.json().get("detail", "")
+        except Exception:
+            detail = str(exc)
+
+        if status == 401:
+            msg = "Invalid credentials."
+            if isinstance(detail, dict):
+                err = detail.get("error", "")
+                if err == "account_deactivated":
+                    msg = "Account deactivated. Contact support."
+            console.print(f"[red]Login failed: {msg}[/red]")
+        elif status == 403:
+            msg = "Access denied."
+            if isinstance(detail, dict):
+                err = detail.get("error", "")
+                if err == "email_not_verified":
+                    msg = (
+                        "Email not verified. "
+                        "Check your inbox and click the verification link."
+                    )
+                elif err == "no_active_organization":
+                    msg = "No active organization found for this account."
+            console.print(f"[red]Login failed: {msg}[/red]")
+        else:
+            console.print(f"[red]Login error ({status}): {detail}[/red]")
+
+        raise SystemExit(1)
+    except httpx.RequestError as exc:
+        console.print(f"[red]Could not reach {api_url}: {exc}[/red]")
+        raise SystemExit(1)
+
+    data = response.json()
+    jwt_token = data.get("access_token")
+    if not jwt_token:
+        console.print("[red]Login succeeded but no access_token in response.[/red]")
+        raise SystemExit(1)
+
+    _save_api_key(jwt_token)
+
+    name = data.get("full_name") or data.get("email") or email
+    console.print(f"[green]Logged in as {name}[/green]")
+    console.print("  Credentials saved to ~/.plugsync/config.yaml")
+
+
+@auth.command("logout")
+def auth_logout():
+    """Remove stored credentials from config.
+
+    Example:
+        plugsync auth logout
+    """
+    cfg = get_config()
+    if "api_key" in cfg:
+        del cfg["api_key"]
+        save_config(cfg)
+        console.print("[green]Logged out - credentials removed.[/green]")
+    else:
+        console.print("[yellow]No credentials stored.[/yellow]")