plugsync-cli 0.1.0__py3-none-any.whl

plugsync_cli/commands/pull.py

@@ -0,0 +1,121 @@
+"""plugsync pull — download connector as local directory."""
+import io
+import zipfile
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from plugsync_cli.client import PlugSyncClient
+from plugsync_cli.serializer import write_directory
+
+console = Console()
+
+
+@click.command()
+@click.argument("connector_name")
+@click.option("--revision", "-r", type=int, default=None, help="Export a specific revision version")
+@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 as a local directory.
+
+    Examples:
+        plugsync pull hubspot-juve
+        plugsync pull hubspot-juve --revision 3
+        plugsync pull hubspot-juve -o ./my-dir
+    """
+    try:
+        client = PlugSyncClient()
+    except RuntimeError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+
+    # Find connector by name
+    connector = client.find_connector(connector_name)
+    if not connector:
+        console.print(f"[red]Connector '{connector_name}' not found[/red]")
+        raise SystemExit(1)
+
+    connector_id = connector["id"]
+
+    # Download ZIP
+    if revision is not None:
+        console.print(f"Exporting revision v{revision} of [bold]{connector_name}[/bold]...")
+        zip_data = client.export_revision(connector_id, revision)
+    else:
+        console.print(f"Exporting [bold]{connector_name}[/bold]...")
+        zip_data = client.export_working_state(connector_id)
+
+    # Extract ZIP to local directory
+    output_dir = Path(output) if output else Path.cwd() / connector_name
+
+    buf = io.BytesIO(zip_data)
+    with zipfile.ZipFile(buf, "r") as zf:
+        # Find the prefix directory in the ZIP
+        names = zf.namelist()
+        if not names:
+            console.print("[red]Empty export[/red]")
+            raise SystemExit(1)
+
+        prefix = names[0].split("/")[0]
+
+        # Parse manifest
+        manifest_content = zf.read(f"{prefix}/plugsync.yaml").decode("utf-8")
+        manifest = yaml.safe_load(manifest_content)
+
+        # Parse entities
+        entities = []
+        for name in sorted(names):
+            if name.startswith(f"{prefix}/entities/") and name.endswith(".yaml"):
+                data = yaml.safe_load(zf.read(name).decode("utf-8"))
+                entity_name = data.get("name", Path(name).stem)
+                config = {}
+                for key in ("entity_type", "hubspot_object_type", "identity", "field_mappings", "associations", "scope_overrides"):
+                    if key in data:
+                        config[key] = data[key]
+                entities.append({"name": entity_name, "config": config})
+
+        # Parse handlers
+        handlers = []
+        for name in sorted(names):
+            if name.startswith(f"{prefix}/handlers/") and name.endswith(".py"):
+                content = zf.read(name).decode("utf-8")
+                lines = content.split("\n")
+                event_type = None
+                code = content
+                if lines[0].startswith("# event_type:"):
+                    event_type = lines[0].split(":", 1)[1].strip()
+                    code = "\n".join(lines[1:]).lstrip("\n")
+
+                if not event_type:
+                    stem = Path(name).stem
+                    event_type = stem.replace("_", ".")
+
+                # Extract function name
+                fn_name = "handler"
+                for line in code.split("\n"):
+                    s = line.strip()
+                    if s.startswith("async def "):
+                        fn_name = s.split("(")[0].replace("async def ", "")
+                        break
+                    elif s.startswith("def "):
+                        fn_name = s.split("(")[0].replace("def ", "")
+                        break
+
+                handlers.append({"event_type": event_type, "function_name": fn_name, "code": code})
+
+    # Write to local directory
+    write_directory(output_dir, manifest, entities, handlers)
+
+    # Write .plugsync.yaml in the directory for context
+    local_config = output_dir / ".plugsync.yaml"
+    local_config.write_text(yaml.dump({
+        "connector": connector_name,
+        "connector_id": connector_id,
+    }, default_flow_style=False))
+
+    entity_count = len(entities)
+    handler_count = len(handlers)
+    console.print(f"[green]Pulled to {output_dir}/[/green]")
+    console.print(f"  {entity_count} entit{'y' if entity_count == 1 else 'ies'}, {handler_count} handler{'s' if handler_count != 1 else ''}")

plugsync_cli/commands/push.py

@@ -0,0 +1,101 @@
+"""plugsync push — upload local directory, validate, and publish."""
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from plugsync_cli.client import PlugSyncClient
+from plugsync_cli.serializer import read_directory_to_zip
+
+console = Console()
+
+
+def _find_connector_dir(path: str | None) -> Path:
+    """Resolve connector directory from argument or cwd."""
+    if path:
+        p = Path(path)
+        if not p.exists():
+            console.print(f"[red]Directory not found: {path}[/red]")
+            raise SystemExit(1)
+        return p
+
+    # Check cwd for plugsync.yaml
+    cwd = Path.cwd()
+    if (cwd / "plugsync.yaml").exists():
+        return cwd
+
+    console.print("[red]No plugsync.yaml found in current directory. Specify a path or cd into a connector directory.[/red]")
+    raise SystemExit(1)
+
+
+def _get_connector_id(connector_dir: Path) -> str:
+    """Read connector_id from .plugsync.yaml."""
+    local_config = connector_dir / ".plugsync.yaml"
+    if local_config.exists():
+        with open(local_config) as f:
+            data = yaml.safe_load(f) or {}
+            cid = data.get("connector_id")
+            if cid:
+                return cid
+
+    console.print("[red]No .plugsync.yaml with connector_id found. Run 'plugsync pull' first.[/red]")
+    raise SystemExit(1)
+
+
+@click.command()
+@click.argument("path", required=False, default=None)
+@click.option("--message", "-m", type=str, default=None, help="Change summary for publish")
+@click.option("--no-publish", is_flag=True, default=False, help="Import without publishing")
+def push(path: str | None, message: str | None, no_publish: bool):
+    """Upload local directory to PluSync, validate, and publish.
+
+    Examples:
+        plugsync push                    # push from cwd
+        plugsync push ./hubspot-juve     # push from specific path
+        plugsync push -m "Added phone"   # with change summary
+        plugsync push --no-publish       # import without publishing
+    """
+    try:
+        client = PlugSyncClient()
+    except RuntimeError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+
+    connector_dir = _find_connector_dir(path)
+    connector_id = _get_connector_id(connector_dir)
+
+    console.print(f"Packing [bold]{connector_dir.name}[/bold]...")
+    zip_data = read_directory_to_zip(connector_dir)
+
+    # Upload
+    console.print("Uploading...")
+    import_result = client.import_zip(connector_id, zip_data)
+    console.print(
+        f"  Imported: {import_result['entities_count']} entities, "
+        f"{import_result['handlers_count']} handlers"
+    )
+
+    # Validate
+    console.print("Validating...")
+    validation = client.validate(connector_id)
+    if not validation["valid"]:
+        console.print("[red]Validation failed:[/red]")
+        for err in validation.get("errors", []):
+            loc = err.get("location", "")
+            msg = err.get("message", "")
+            console.print(f"  [red]{loc}: {msg}[/red]")
+        console.print("[yellow]Changes imported but NOT published. Fix errors and push again.[/yellow]")
+        raise SystemExit(1)
+
+    console.print("[green]Validation passed[/green]")
+
+    if no_publish:
+        console.print("[yellow]Skipping publish (--no-publish). Changes are in working state.[/yellow]")
+        return
+
+    # Publish
+    console.print("Publishing...")
+    pub_result = client.publish(connector_id, change_summary=message)
+    version = pub_result.get("version", "?")
+    console.print(f"[green]Published revision v{version}[/green]")

plugsync_cli/commands/rollback.py

@@ -0,0 +1,72 @@
+"""plugsync rollback — restore working state from a past revision."""
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from plugsync_cli.client import PlugSyncClient
+
+console = Console()
+
+
+def _parse_version(version_str: str) -> int:
+    """Parse version from 'v3' or '3'."""
+    cleaned = version_str.strip().lower().lstrip("v")
+    try:
+        return int(cleaned)
+    except ValueError:
+        console.print(f"[red]Invalid version: '{version_str}'. Use 'v3' or '3'.[/red]")
+        raise SystemExit(1)
+
+
+@click.command()
+@click.argument("version")
+@click.argument("connector_name", required=False, default=None)
+def rollback(version: str, connector_name: str | None):
+    """Restore working state from a past revision.
+
+    This overwrites the current working state with the specified revision.
+    Does NOT auto-publish. Run 'plugsync push' to publish the restored state.
+
+    Examples:
+        plugsync rollback v3
+        plugsync rollback 3
+        plugsync rollback v3 hubspot-juve
+    """
+    try:
+        client = PlugSyncClient()
+    except RuntimeError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+
+    ver = _parse_version(version)
+
+    # Resolve connector_id
+    connector_id = None
+    if connector_name:
+        connector = client.find_connector(connector_name)
+        if not connector:
+            console.print(f"[red]Connector '{connector_name}' not found[/red]")
+            raise SystemExit(1)
+        connector_id = connector["id"]
+    else:
+        local_config = Path.cwd() / ".plugsync.yaml"
+        if local_config.exists():
+            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]Specify a connector name or run from a connector directory.[/red]")
+            raise SystemExit(1)
+
+    console.print(f"Restoring to v{ver}...")
+    result = client.restore_revision(connector_id, ver)
+
+    if result.get("restored"):
+        console.print(f"[green]Working state restored to v{ver}[/green]")
+        console.print(f"Run [bold]plugsync push[/bold] to publish, or [bold]plugsync pull[/bold] to update local files.")
+    else:
+        console.print(f"[red]Failed to restore v{ver}[/red]")
+        raise SystemExit(1)

plugsync_cli/commands/validate.py

@@ -0,0 +1,66 @@
+"""plugsync validate — validate current connector state."""
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from plugsync_cli.client import PlugSyncClient
+from plugsync_cli.serializer import read_directory_to_zip
+
+console = Console()
+
+
+@click.command()
+@click.argument("path", required=False, default=None)
+def validate(path: str | None):
+    """Validate the connector configuration.
+
+    Uploads the local state to the server and runs validation
+    (schema, syntax, referential integrity).
+
+    Examples:
+        plugsync validate
+        plugsync validate ./hubspot-juve
+    """
+    try:
+        client = PlugSyncClient()
+    except RuntimeError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+
+    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 validation)
+    zip_data = read_directory_to_zip(connector_dir)
+    click.confirm(
+        "This will upload your local files to the remote working state. Continue?",
+        abort=True,
+    )
+    client.import_zip(connector_id, zip_data)
+
+    # Validate
+    result = client.validate(connector_id)
+
+    if result["valid"]:
+        console.print("[green]Validation passed[/green]")
+        return
+
+    console.print("[red]Validation failed:[/red]")
+    for err in result.get("errors", []):
+        loc = err.get("location", "")
+        msg = err.get("message", "")
+        console.print(f"  [red]{loc}: {msg}[/red]")
+    raise SystemExit(1)

plugsync_cli/compat.py

@@ -0,0 +1,73 @@
+"""API version compatibility check (issue #957).
+
+The CLI ships on its own semver line, independent of the backend release
+train. This module declares the minimum backend API version the current
+CLI build expects, and checks it against the API's version endpoint
+before any command that talks to the API runs.
+
+As of this writing the backend does not expose that version endpoint yet
+(tracked in issue #992) -- until it ships, every check degrades
+gracefully to a silent no-op rather than a hard failure: an
+absent/unreachable endpoint is evidence of an API that hasn't been
+instrumented yet, not of one that's incompatible.
+"""
+import httpx
+from rich.console import Console
+
+# Minimum backend API version this CLI build expects. Bump when a CLI
+# release starts depending on an API contract older backends don't have.
+MIN_API_VERSION = "1.0.0"
+
+console = Console()
+
+
+def _parse_version(value: str) -> tuple[int, ...] | None:
+    """Parse a dotted numeric version ("1.4.2") into a tuple, or None if unparseable."""
+    try:
+        return tuple(int(part) for part in value.strip().split("."))
+    except (ValueError, AttributeError):
+        return None
+
+
+def check_api_compat(api_url: str, min_version: str = MIN_API_VERSION) -> None:
+    """Warn if the API at ``api_url`` reports a version older than ``min_version``.
+
+    Never raises: any failure to determine the API's version (missing
+    endpoint, unreachable host, malformed response, unparseable version
+    string) is treated as "unknown" and silently skipped, so a backend
+    without the version endpoint is no worse off than one with it.
+    """
+    try:
+        response = httpx.get(f"{api_url}/api/version", timeout=5.0)
+    except httpx.RequestError:
+        return
+
+    if response.status_code == 404:
+        return
+
+    try:
+        response.raise_for_status()
+        api_version = response.json()["api_version"]
+    except Exception:
+        return
+
+    current = _parse_version(api_version)
+    minimum = _parse_version(min_version)
+    if current is None or minimum is None:
+        return
+
+    # Pad to equal length before comparing: tuple comparison in Python
+    # compares element-wise and falls back to length when one is a prefix
+    # of the other, so (1, 0) < (1, 0, 0) is True even though "1.0" and
+    # "1.0.0" are the same version.
+    width = max(len(current), len(minimum))
+    current_padded = current + (0,) * (width - len(current))
+    minimum_padded = minimum + (0,) * (width - len(minimum))
+
+    if current_padded < minimum_padded:
+        console.print(
+            f"[yellow]Warning: API at {api_url} reports version {api_version}, "
+            f"below the minimum {min_version} this CLI expects. Some commands "
+            "may not work correctly. Upgrade the API, or install a matching "
+            "plugsync-cli version.[/yellow]"
+        )

plugsync_cli/config.py

@@ -0,0 +1,51 @@
+"""Manage ~/.plugsync/config.yaml for CLI authentication and settings."""
+import os
+from pathlib import Path
+
+import yaml
+
+CONFIG_DIR = Path.home() / ".plugsync"
+CONFIG_FILE = CONFIG_DIR / "config.yaml"
+
+
+def get_config() -> dict:
+    """Load config from ~/.plugsync/config.yaml."""
+    if not CONFIG_FILE.exists():
+        return {}
+    with open(CONFIG_FILE) as f:
+        return yaml.safe_load(f) or {}
+
+
+def save_config(config: dict) -> None:
+    """Save config to ~/.plugsync/config.yaml."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_FILE, "w") as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+
+def get_api_url() -> str:
+    """Get the API base URL from config or environment."""
+    env_url = os.environ.get("PLUGSYNC_API_URL")
+    if env_url:
+        return env_url.rstrip("/")
+    config = get_config()
+    return config.get("api_url", "http://localhost:8013").rstrip("/")
+
+
+def get_api_key() -> str | None:
+    """Get the org API key from config or environment."""
+    env_key = os.environ.get("PLUGSYNC_API_KEY")
+    if env_key:
+        return env_key
+    config = get_config()
+    return config.get("api_key")
+
+
+def get_default_connector() -> str | None:
+    """Get the default connector name from local .plugsync.yaml in cwd."""
+    local_config = Path.cwd() / ".plugsync.yaml"
+    if local_config.exists():
+        with open(local_config) as f:
+            data = yaml.safe_load(f) or {}
+            return data.get("connector")
+    return None

plugsync_cli/main.py

@@ -0,0 +1,84 @@
+"""PluSync CLI entry point — git-like connector management."""
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.group()
+@click.version_option(package_name="plugsync-cli")
+def cli():
+    """PluSync CLI — manage connectors like code."""
+    pass
+
+
+@cli.group()
+def config():
+    """Manage CLI configuration."""
+    pass
+
+
+@config.command("set")
+@click.argument("key")
+@click.argument("value")
+def config_set(key: str, value: str):
+    """Set a configuration value (api_url, api_key)."""
+    from plugsync_cli.config import get_config, save_config
+
+    cfg = get_config()
+    cfg[key] = value
+    save_config(cfg)
+    console.print(f"[green]Set {key}[/green]")
+
+
+@config.command("get")
+@click.argument("key")
+def config_get(key: str):
+    """Get a configuration value."""
+    from plugsync_cli.config import get_config
+
+    cfg = get_config()
+    value = cfg.get(key)
+    if value:
+        console.print(value)
+    else:
+        console.print(f"[yellow]{key} not set[/yellow]")
+
+
+@config.command("show")
+def config_show():
+    """Show all configuration values."""
+    from plugsync_cli.config import get_config
+
+    cfg = get_config()
+    if not cfg:
+        console.print("[yellow]No configuration set. Run 'plugsync config set api_key <key>'[/yellow]")
+        return
+    for key, value in cfg.items():
+        if key == "api_key":
+            # Mask the key
+            display = value[:8] + "..." if len(value) > 8 else "***"
+            console.print(f"  {key}: {display}")
+        else:
+            console.print(f"  {key}: {value}")
+
+
+from plugsync_cli.commands.pull import pull
+from plugsync_cli.commands.push import push
+from plugsync_cli.commands.diff import diff
+from plugsync_cli.commands.validate import validate
+from plugsync_cli.commands.preview import preview
+from plugsync_cli.commands.log import log_cmd
+from plugsync_cli.commands.rollback import rollback
+from plugsync_cli.commands.plugin import plugin
+from plugsync_cli.commands.auth import auth
+
+cli.add_command(pull)
+cli.add_command(push)
+cli.add_command(diff)
+cli.add_command(validate)
+cli.add_command(preview)
+cli.add_command(log_cmd)
+cli.add_command(rollback)
+cli.add_command(plugin)
+cli.add_command(auth)