plugsync-cli 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

plugsync_cli/__init__.py

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

plugsync_cli/client.py

@@ -145,6 +145,98 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
+    def prewarm_start(
+        self,
+        connector_id: str,
+        *,
+        dry_run: bool = False,
+        modified_after: str | None = None,
+        entities: list[str] | None = None,
+        store_id: str | None = None,
+    ) -> dict:
+        """Start an identity map pre-warm job (#1885), returning the job.
+
+        The API answers 202 with the job already running in the background;
+        progress is read back with `prewarm_get`. `modified_after` is an ISO
+        8601 timestamp with a timezone and turns the run into an incremental
+        pass. Unset options are left out of the body so the server defaults
+        apply.
+        """
+        body: dict = {"dry_run": dry_run}
+        if modified_after is not None:
+            body["modified_after"] = modified_after
+        if entities:
+            body["entities"] = list(entities)
+        if store_id is not None:
+            body["store_id"] = store_id
+        with self._client() as c:
+            r = c.post(
+                self._url(f"/connectors/{connector_id}/identity-prewarm"), json=body
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def prewarm_list(self, connector_id: str) -> list[dict]:
+        """The connector's most recent pre-warm jobs, newest first."""
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/identity-prewarm"))
+            r.raise_for_status()
+            return r.json().get("jobs", [])
+
+    def prewarm_get(self, connector_id: str, job_id: str) -> dict:
+        """One pre-warm job with its per-entity progress."""
+        with self._client() as c:
+            r = c.get(
+                self._url(f"/connectors/{connector_id}/identity-prewarm/{job_id}")
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def prewarm_findings(
+        self,
+        connector_id: str,
+        job_id: str,
+        *,
+        finding: str | None = None,
+        limit: int = 200,
+        offset: int = 0,
+    ) -> dict:
+        """A page of a job's findings: ambiguous values and conflicting mappings."""
+        params: dict = {"limit": limit, "offset": offset}
+        if finding is not None:
+            params["finding"] = finding
+        with self._client() as c:
+            r = c.get(
+                self._url(
+                    f"/connectors/{connector_id}/identity-prewarm/{job_id}/findings"
+                ),
+                params=params,
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def prewarm_resume(self, connector_id: str, job_id: str) -> dict:
+        """Resume an interrupted or failed pre-warm job from its cursor."""
+        with self._client() as c:
+            r = c.post(
+                self._url(
+                    f"/connectors/{connector_id}/identity-prewarm/{job_id}/resume"
+                )
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def prewarm_cancel(self, connector_id: str, job_id: str) -> dict:
+        """Cancel a pre-warm job for good: it cannot be resumed afterwards."""
+        with self._client() as c:
+            r = c.post(
+                self._url(
+                    f"/connectors/{connector_id}/identity-prewarm/{job_id}/cancel"
+                )
+            )
+            r.raise_for_status()
+            return r.json()
+
     def get_draft(self, connector_id: str) -> dict:
         """The connector's editable config (backend DraftResponse).
 

plugsync_cli/commands/connector.py

@@ -1,4 +1,4 @@
-"""plugsync connector -- read a connector's flow circuit breakers, retry one.
+"""plugsync connector -- flow circuit breakers and the identity map pre-warm.
 
 Self-service only, with the same org-scoped auth as every other command: the
 owner of a connector lists the flows whose circuit breaker is open and retries
@@ -6,7 +6,14 @@ one of them, from a script or from CI, without opening the dashboard. The
 platform-side force-close is a different operation with a different
 authentication contract (it refuses an org API key) and deliberately has no
 command here.
+
+`connector prewarm` drives the identity map pre-warm of a migration cutover
+(#1885): it fills the connector's identity map from records already on the
+HubSpot portal, so the first events after go-live update them instead of
+searching for them. The job runs server-side; these commands start it, read
+its progress, resume it and list what it could not map.
 """
+import time
 import uuid
 from datetime import datetime, timezone
 
@@ -251,3 +258,402 @@ def connector_breakers(connector_reference: str):
         "by the next message it receives.\n",
         soft_wrap=True,
     )
+
+
+# ---------------------------------------------------------------------------
+# Identity map pre-warm (#1885)
+# ---------------------------------------------------------------------------
+
+_PREWARM_TERMINAL = frozenset({
+    "completed", "partial_failure", "failed", "cancelled", "superseded", "expired",
+})
+_PREWARM_POLL_SECONDS = 5
+# --wait outlives a deploy of the API or a network blip: the job runs on the
+# server either way. This many polls in a row may fail before it gives up.
+_PREWARM_POLL_MAX_FAILURES = 12
+
+# Machine codes of the pre-warm API whose own message is the whole story.
+_PREWARM_ERRORS = frozenset({
+    "no_active_config",
+    "no_eligible_entities",
+    "entity_not_eligible",
+    "prewarm_already_running",
+    "job_not_resumable",
+    "job_not_cancellable",
+})
+
+
+def _structured_detail(exc: httpx.HTTPStatusError) -> dict:
+    try:
+        payload = exc.response.json()
+    except ValueError:
+        return {}
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    return detail if isinstance(detail, dict) else {}
+
+
+def _prewarm_call(label: str, call, *args, **kwargs):
+    """Run one pre-warm request, turning the API's refusals into sentences."""
+    try:
+        return call(*args, **kwargs)
+    except httpx.HTTPStatusError as exc:
+        detail = _structured_detail(exc)
+        code = detail.get("error")
+        if exc.response.status_code == 404:
+            if code == "job_not_found":
+                fail(f"Pre-warm job not found on connector '{label}'.")
+            fail(_CONNECTOR_NOT_FOUND.format(label=label))
+        if code in _PREWARM_ERRORS:
+            message = detail.get("message") or code
+            if code == "entity_not_eligible":
+                message += (
+                    f" Not eligible: {', '.join(detail.get('entities') or [])}."
+                    f" Eligible: {', '.join(detail.get('eligible') or []) or 'none'}."
+                )
+            fail(f"{message} ({code})")
+        raise
+
+
+def _render_job(job: dict) -> None:
+    """A job's header line and its per-entity counters."""
+    mode = "dry-run" if job.get("dry_run") else "write"
+    scope = (
+        f"incremental after {job['modified_after']}"
+        if job.get("modified_after") else "full"
+    )
+    store = f", store '{job['store_id']}'" if job.get("store_id") else ""
+    console.print(
+        f"\n[bold]Pre-warm {job.get('job_id')}[/bold]: {job.get('status')} "
+        f"({mode}, {scope}{store})",
+        soft_wrap=True,
+    )
+
+    # Single-cell padding: eight columns at the default two overflow an
+    # 80-column terminal and rich starts truncating the counters.
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 1))
+    table.add_column("Entity", overflow="fold")
+    table.add_column("Phase")
+    for column in ("Scanned", "Mapped", "Present", "Conflicts", "Ambiguous", "Skipped"):
+        table.add_column(column, justify="right")
+    skipped_notes = []
+    for entry in job.get("entities") or []:
+        missing = entry.get("missing_value", 0)
+        invalid = entry.get("invalid_value", 0)
+        unmodified = entry.get("not_modified", 0)
+        skipped = missing + invalid + unmodified
+        table.add_row(
+            str(entry.get("entity") or ""),
+            str(entry.get("phase") or ""),
+            str(entry.get("scanned", 0)),
+            str(entry.get("mapped", 0)),
+            str(entry.get("already_present", 0)),
+            str(entry.get("conflicting", 0)),
+            str(entry.get("ambiguous_values", 0)),
+            str(skipped),
+        )
+        if skipped:
+            skipped_notes.append(
+                f"{entry.get('entity')}: skipped {missing} without an identity value, "
+                f"{invalid} with an invalid one, {unmodified} not modified since "
+                "the cutoff."
+            )
+        if entry.get("mapped_elsewhere"):
+            skipped_notes.append(
+                f"{entry.get('entity')}: {entry['mapped_elsewhere']} records already "
+                "mapped under another external id, not mapped again."
+            )
+        if entry.get("ambiguous_values"):
+            skipped_notes.append(
+                f"{entry.get('entity')}: {entry['ambiguous_values']} ambiguous values "
+                f"held by {entry.get('ambiguous_records', 0)} records, not mapped."
+            )
+    console.print(table)
+    for note in skipped_notes:
+        console.print(note, soft_wrap=True)
+
+    for entry in job.get("entities") or []:
+        if entry.get("error"):
+            console.print(
+                f"[red]{entry.get('entity')}: {entry['error']}[/red]", soft_wrap=True
+            )
+    if job.get("last_error"):
+        console.print(f"[red]Job error: {job['last_error']}[/red]", soft_wrap=True)
+    if job.get("dry_run") and job.get("status") in _PREWARM_TERMINAL:
+        console.print("Dry run: nothing was written. 'Mapped' is what a real run would write.")
+    if job.get("resumable"):
+        console.print(
+            f"Resumable from where it stopped: plugsync connector prewarm resume "
+            f"<connector> {job.get('job_id')}",
+            soft_wrap=True,
+        )
+
+
+def _has_findings(job: dict) -> bool:
+    return any(
+        (entry.get("ambiguous_values") or 0) or (entry.get("conflicting") or 0)
+        or (entry.get("mapped_elsewhere") or 0)
+        for entry in job.get("entities") or []
+    )
+
+
+def _is_transient(exc: Exception) -> bool:
+    """A failed poll that says nothing about the job: the API restarting
+    (5xx), a rate limit, the network."""
+    if isinstance(exc, httpx.HTTPStatusError):
+        return exc.response.status_code >= 500 or exc.response.status_code == 429
+    return isinstance(exc, httpx.TransportError)
+
+
+def _wait_for(client: PlugSyncClient, connector_id: str, label: str, job: dict) -> dict:
+    """Poll a job until it reaches a terminal status.
+
+    A poll that fails for a transient reason is tried again at the next
+    tick: the job runs on the server and is not affected, so exiting
+    non-zero here would report a failure that did not happen. After
+    `_PREWARM_POLL_MAX_FAILURES` failed polls in a row it gives up, saying
+    that the job's state is unknown, not that it failed.
+    """
+    failures = 0
+    while job.get("status") not in _PREWARM_TERMINAL:
+        if job.get("resumable"):
+            # A running job whose heartbeat went stale: nobody is advancing it.
+            break
+        time.sleep(_PREWARM_POLL_SECONDS)
+        try:
+            job = _prewarm_call(label, client.prewarm_get, connector_id, str(job["job_id"]))
+        except (httpx.HTTPStatusError, httpx.TransportError) as exc:
+            if not _is_transient(exc):
+                raise
+            failures += 1
+            reason = (
+                f"HTTP {exc.response.status_code}"
+                if isinstance(exc, httpx.HTTPStatusError) else type(exc).__name__
+            )
+            if failures >= _PREWARM_POLL_MAX_FAILURES:
+                fail(
+                    f"Lost contact with the API while waiting ({failures} polls "
+                    f"failed in a row, last: {reason}). The pre-warm may still be "
+                    f"running: check it with plugsync connector prewarm status "
+                    f"{label} {job.get('job_id')}"
+                )
+            console.print(
+                f"[yellow]Status poll failed ({reason}), retrying "
+                f"({failures}/{_PREWARM_POLL_MAX_FAILURES}).[/yellow]",
+                soft_wrap=True,
+            )
+            continue
+        failures = 0
+    return job
+
+
+def _finish(job: dict, label: str) -> None:
+    """Report a job `--wait` stopped on; exit non-zero unless it completed."""
+    _render_job(job)
+    if _has_findings(job):
+        console.print(
+            f"Review what was not mapped: plugsync connector prewarm findings "
+            f"{label} {job.get('job_id')}",
+            soft_wrap=True,
+        )
+    status = job.get("status")
+    if status not in _PREWARM_TERMINAL:
+        # --wait gave up on a job nobody is advancing: a script chaining the
+        # cutover on this exit code must not read that as a finished pre-warm.
+        console.print(
+            f"[red]The pre-warm stopped advancing before it finished "
+            f"(status: {status}).[/red]",
+            soft_wrap=True,
+        )
+    if status != "completed":
+        raise SystemExit(1)
+
+
+@connector.group()
+def prewarm():
+    """Pre-warm a connector's identity map from its HubSpot portal."""
+    pass
+
+
+@prewarm.command("start")
+@click.argument("connector_reference", metavar="CONNECTOR")
+@click.option("--dry-run", is_flag=True,
+              help="Count per entity what would be mapped, write nothing.")
+@click.option("--modified-after", metavar="TIMESTAMP",
+              help="Incremental pass: map only records modified after this ISO 8601 "
+                   "timestamp, with a timezone (e.g. 2026-10-01T08:00:00Z).")
+@click.option("--entity", "entities", multiple=True, metavar="ENTITY",
+              help="Limit the run to this entity. Repeatable. Default: every entity "
+                   "with a HubSpot schema and an identity property.")
+@click.option("--store-id", metavar="STORE",
+              help="Store id of the keys written. Only for records that will arrive "
+                   "through bulk import with that storeId; event flows need none.")
+@click.option("--wait", is_flag=True,
+              help="Poll until the job finishes and exit non-zero if it did not complete.")
+def prewarm_start(connector_reference: str, dry_run: bool, modified_after: str | None,
+                  entities: tuple[str, ...], store_id: str | None, wait: bool):
+    """Start an identity map pre-warm.
+
+    CONNECTOR is a connector name or id. The job reads every record of the
+    eligible entities from HubSpot and writes the identity mappings that are
+    missing. Existing mappings are never overwritten, and a value held by more
+    than one HubSpot record is reported as ambiguous instead of mapped.
+
+    Examples:
+        plugsync connector prewarm start my-connector --dry-run --wait
+        plugsync connector prewarm start my-connector
+        plugsync connector prewarm start my-connector --modified-after 2026-10-01T08:00:00Z --wait
+    """
+    if modified_after is not None:
+        try:
+            parsed = datetime.fromisoformat(modified_after.replace("Z", "+00:00"))
+        except ValueError:
+            fail(f"--modified-after '{modified_after}' is not an ISO 8601 timestamp.")
+        if parsed.tzinfo is None:
+            fail("--modified-after needs a timezone, e.g. 2026-10-01T08:00:00Z.")
+
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+    job = _prewarm_call(
+        label, client.prewarm_start, connector_id,
+        dry_run=dry_run, modified_after=modified_after,
+        entities=list(entities) or None, store_id=store_id,
+    )
+    if not wait:
+        _render_job(job)
+        console.print(
+            f"Follow it with: plugsync connector prewarm status {label} {job.get('job_id')}",
+            soft_wrap=True,
+        )
+        return
+    _finish(_wait_for(client, connector_id, label, job), label)
+
+
+@prewarm.command("status")
+@click.argument("connector_reference", metavar="CONNECTOR")
+@click.argument("job_id", required=False)
+@click.option("--wait", is_flag=True, help="Poll until the job finishes.")
+def prewarm_status(connector_reference: str, job_id: str | None, wait: bool):
+    """Show a pre-warm job's progress (default: the most recent job).
+
+    Examples:
+        plugsync connector prewarm status my-connector
+        plugsync connector prewarm status my-connector <job-id> --wait
+    """
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+    if job_id is None:
+        jobs = _prewarm_call(label, client.prewarm_list, connector_id)
+        if not jobs:
+            console.print(f"No pre-warm job on '{label}' yet.")
+            return
+        job = jobs[0]
+    else:
+        job = _prewarm_call(label, client.prewarm_get, connector_id, job_id)
+    if wait:
+        _finish(_wait_for(client, connector_id, label, job), label)
+        return
+    _render_job(job)
+
+
+@prewarm.command("resume")
+@click.argument("connector_reference", metavar="CONNECTOR")
+@click.argument("job_id")
+@click.option("--wait", is_flag=True, help="Poll until the job finishes.")
+def prewarm_resume(connector_reference: str, job_id: str, wait: bool):
+    """Resume a failed or interrupted pre-warm from its last saved page.
+
+    A job can be resumed when it failed (for example after a long HubSpot
+    rate limit) or when it is marked running but its heartbeat is older than
+    five minutes (the process running it stopped). Only the connector's
+    latest job can be resumed, and never a cancelled, superseded or expired
+    one: start a new pre-warm instead.
+    """
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+    job = _prewarm_call(label, client.prewarm_resume, connector_id, job_id)
+    if wait:
+        _finish(_wait_for(client, connector_id, label, job), label)
+        return
+    _render_job(job)
+
+
+@prewarm.command("cancel")
+@click.argument("connector_reference", metavar="CONNECTOR")
+@click.argument("job_id")
+def prewarm_cancel(connector_reference: str, job_id: str):
+    """Cancel a pre-warm job for good.
+
+    Works on a queued, running or failed job. Use it to stop a run, or to
+    free a connector whose job is stuck in `running` because the process
+    running it stopped: until then no new pre-warm can start. A running job
+    stops at its next page. The mappings already written stay (a later run
+    finds them present); the job's staged values are deleted and it can
+    never be resumed.
+
+    Example:
+        plugsync connector prewarm cancel my-connector <job-id>
+    """
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+    job = _prewarm_call(label, client.prewarm_cancel, connector_id, job_id)
+    _render_job(job)
+    console.print(
+        f"Cancelled. Start again with: plugsync connector prewarm start {label}",
+        soft_wrap=True,
+    )
+
+
+@prewarm.command("findings")
+@click.argument("connector_reference", metavar="CONNECTOR")
+@click.argument("job_id")
+@click.option("--finding",
+              type=click.Choice(["ambiguous", "conflict", "mapped_elsewhere"]),
+              help="Only this kind of finding.")
+@click.option("--limit", type=click.IntRange(1, 1000), default=200, show_default=True)
+@click.option("--offset", type=click.IntRange(0), default=0, show_default=True)
+def prewarm_findings(connector_reference: str, job_id: str, finding: str | None,
+                     limit: int, offset: int):
+    """List what a pre-warm could not map.
+
+    `ambiguous`: the same identity value is held by several HubSpot records,
+    so no mapping was written; deduplicate them on the portal and run the
+    pre-warm again. `conflict`: the identity map already maps the value to a
+    different record and was left untouched. `mapped_elsewhere`: the record
+    is already mapped under another external id (shown in the last column),
+    so it was not given a second mapping.
+    """
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+    page = _prewarm_call(
+        label, client.prewarm_findings, connector_id, job_id,
+        finding=finding, limit=limit, offset=offset,
+    )
+    rows = page.get("findings") or []
+    total = page.get("total", len(rows))
+    if not rows:
+        console.print(f"[green]No findings for job {job_id}.[/green]")
+        return
+
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    table.add_column("Entity")
+    table.add_column("Finding")
+    table.add_column("Value", overflow="fold")
+    table.add_column("HubSpot id")
+    table.add_column("Mapped to")
+    for row in rows:
+        table.add_row(
+            str(row.get("entity") or ""),
+            str(row.get("finding") or ""),
+            str(row.get("value") or ""),
+            str(row.get("hubspot_id") or ""),
+            str(row.get("existing_hubspot_id") or row.get("existing_external_id") or ""),
+        )
+    console.print(table)
+    shown_to = offset + len(rows)
+    console.print(f"\n{offset + 1}-{shown_to} of {total}.")
+    if shown_to < total:
+        console.print(
+            f"Next page: plugsync connector prewarm findings {label} {job_id} "
+            f"--offset {shown_to}",
+            soft_wrap=True,
+        )

plugsync_cli/commands/diff.py

@@ -63,7 +63,8 @@ console = Console()
 # Top-level config keys compared item-by-item (keyed by name) rather than whole.
 # `sources` reads like the other two here: a published version from before the
 # sources were versioned simply carries no key, so every local source shows up
-# as added, which is what it is against that version.
+# as added, which is what it is against that version. The local side always
+# declares the key: `read_config_directory` refuses a directory that does not.
 COLLECTIONS = {"entities": "entity", "flows": "flow", "sources": "source"}
 
 # Keys listed in one Detail cell before the rest is summarized. A row exists to
@@ -235,37 +236,25 @@ def _diff_configs(local: dict, remote: dict, root: SchemaNode) -> list[dict]:
 
 
 def _declaration_change(key: str, local: dict, remote: dict) -> list[dict]:
-    """The row for a collection one side declares and the other does not.
-
-    Only an optional collection can be in that position, and for `sources` the
-    difference between "declared, and empty" and "not declared at all" is the
-    whole point of the key: the first puts the definitions under the
-    connector's config, the second leaves them to whatever manages them outside
-    it. Item by item the two sides look identical -- no sources either way --
-    so without this row the operator sees nothing at all, and the direction
-    that DROPS the key is the one that reads as "no changes" while changing
-    which document owns the definitions.
+    """The row for a collection the local files declare and the version does not.
+
+    Only an optional collection can be in that position, and only one way
+    round: the local directory always declares `sources` (a directory that does
+    not is refused before this runs), while a version published before the
+    sources were part of the config carries no key. Item by item "declared, and
+    empty" reads the same as that historical absence -- no sources either way
+    -- so without this row a directory with `sources: []` would diff clean
+    against a version that says nothing about sources.
     """
-    if key not in OPTIONAL_COLLECTIONS:
+    if key not in OPTIONAL_COLLECTIONS or remote.get(key) is not None:
         return []
-    in_local, in_remote = local.get(key) is not None, remote.get(key) is not None
-    if in_local == in_remote:
-        return []
-    if in_local:
-        return [
-            _simple(
-                f"{key}_key_added",
-                key,
-                f"declared in your files, absent from the published version: "
-                f"publishing them puts the {key} under the connector's config",
-            )
-        ]
     return [
         _simple(
-            f"{key}_key_removed",
+            f"{key}_key_added",
             key,
-            f"declared in the published version, absent from your files: "
-            f"pushing this directory takes the {key} out of the config",
+            f"declared in your files, absent from the published version, which "
+            f"predates {key} being part of the config: publishing makes the "
+            f"config the authority for the connector's {key}",
         )
     ]
 

plugsync_cli/commands/plugin.py

@@ -35,6 +35,16 @@ export async function handler(event: Record<string, unknown>): Promise<object> {
     flow_name: event.flow_name,
   }));
   // TODO: implement your plugin logic here
+  //
+  // The response is a plain object; later flow steps read any key of it as
+  // `$<step_id>.<key>`. Keys the runtime interprets:
+  //   return { action: "skip" };                         // stop the flow here
+  //   return { action: "retry", reason: "HTTP 503" };    // transient, retried
+  //   return { outcome: "failed", reason: "rejected" };  // target refused the
+  //       record: later steps still run, the record ends failed and replayable
+  //   store_writes: [{ key, value, ttl_seconds? }]       // needs store:write;
+  //       keys persist for the life of the connector (deleted with it);
+  //       ttl_seconds opts a key into expiry
   return {};
 }
 """

plugsync_cli/commands/push.py

@@ -137,7 +137,37 @@ def _publish(client, connector_id: str, message: str | None, republish: bool = F
         )
         return
     console.print(f"[green]Published v{result.get('version')}[/green]")
+    _reveal_created_secrets(result.get("created_sources") or [])
     warnings = result.get("warnings") or []
     if warnings:
         console.print("\nPublished with warnings:")
         render_findings(console, warnings)
+
+
+def _reveal_created_secrets(created_sources: list[dict]) -> None:
+    """Print the plaintext secrets of the webhook sources this publish created.
+
+    A `webhook` source declared in the config is created by the publish itself
+    (ADR-0026), and the publish response is the ONLY place its secret ever
+    appears: nothing reads it back afterwards. Printing it here is what keeps
+    `plugsync push --publish` a complete way to stand a webhook source up;
+    without it the only way to a usable secret is to rotate the one that was
+    just generated. Sources with no secret to generate (every non-webhook
+    type) are skipped rather than printed as a bare name.
+    """
+    revealed = [s for s in created_sources if s.get("secret")]
+    if not revealed:
+        return
+    plural = "s" if len(revealed) > 1 else ""
+    console.print(
+        f"\n[bold]Webhook secret{plural} for the source{plural} this publish "
+        f"created - shown only once:[/bold]"
+    )
+    for source in revealed:
+        console.print(f"  {source['name']}: [bold]{source['secret']}[/bold]")
+    console.print(
+        "[yellow]Copy each value now and configure it in the external system "
+        "that signs that source's deliveries. A secret is never shown again: "
+        "if one is lost, rotate the secret of that source from the dashboard "
+        "to issue a new one.[/yellow]"
+    )

plugsync_cli/context.py

@@ -22,6 +22,7 @@ from plugsync_cli.serializer import (
     locate_in_directory,
     read_config_directory,
     read_local_state,
+    undeclared_collection_message,
     write_config_directory,
     write_local_state,
 )
@@ -131,17 +132,7 @@ def write_draft_from_directory(
     fires every time stops being read exactly when it matters.
     """
     config = context.config()
-    # Read once, shared: the warning below and the concurrency guard both want
-    # the remote draft, and neither is worth a round trip of its own.
-    remote_draft = (
-        client.get_draft(context.connector_id) if config.get("sources") is None else None
-    )
-    if remote_draft is not None:
-        warn_if_the_push_takes_the_sources_out_of_the_config(remote_draft["config"])
-
-    expected_version = (
-        None if force else _expected_draft_version(client, context, remote_draft)
-    )
+    expected_version = None if force else _expected_draft_version(client, context)
     try:
         draft = client.put_draft(
             context.connector_id, config, expected_version=expected_version
@@ -153,7 +144,7 @@ def write_draft_from_directory(
             "'plugsync push --force' to overwrite theirs."
         )
     except httpx.HTTPStatusError as exc:
-        fail(_rejection_pointing_at_the_files(exc))
+        fail(_rejection_pointing_at_the_files(exc, context))
 
     warn_if_flow_order_is_not_preserved(draft["config"])
     write_config_directory(context.directory, draft["config"])
@@ -170,7 +161,24 @@ def write_draft_from_directory(
     return draft
 
 
-def _rejection_pointing_at_the_files(exc: httpx.HTTPStatusError) -> str:
+# The API's error code for a draft write that omits `sources` on a connector
+# that declares them. `read_config_directory` refuses such a directory before
+# any request, so reaching it means the check was bypassed or the API moved.
+SOURCES_KEY_REMOVAL_ERROR = "sources_key_removal_not_supported"
+
+
+def _api_error_code(exc: httpx.HTTPStatusError) -> str | None:
+    """The machine-readable `detail.error` of a structured API refusal."""
+    try:
+        detail = exc.response.json().get("detail")
+    except (ValueError, AttributeError):
+        return None
+    return detail.get("error") if isinstance(detail, dict) else None
+
+
+def _rejection_pointing_at_the_files(
+    exc: httpx.HTTPStatusError, context: ConnectorContext
+) -> str:
     """The API's refusal, with every config path it names resolved to a file.
 
     A rejected draft is described the way the config document reads
@@ -178,7 +186,12 @@ def _rejection_pointing_at_the_files(exc: httpx.HTTPStatusError) -> str:
     operator is looking at it: they have a directory of files open. Naming the
     file that holds the key, alongside the backend's own explanation, is what
     makes the failure actionable without decoding the path by hand.
+
+    A refusal to drop `sources` is about the directory as a whole, not a key in
+    it, so it gets the CLI's own explanation instead of the server's JSON.
     """
+    if _api_error_code(exc) == SOURCES_KEY_REMOVAL_ERROR:
+        return undeclared_collection_message(context.directory, "sources")
     message = describe_http_error(exc)
     located = locate_in_directory(message)
     if not located:
@@ -192,10 +205,10 @@ def _rejection_pointing_at_the_files(exc: httpx.HTTPStatusError) -> str:
 def describe_config(config: dict) -> str:
     """What a config holds, counted, for the line a pull or a push ends on.
 
-    `sources` is reported only when the config declares the key. Its absence
-    means the connector's sources are not versioned in the config at all, which
-    is not the same as having none: printing "0 sources" would say the opposite
-    of what an absent key means.
+    `sources` is reported only when the config declares the key. Only a
+    version published before the sources were part of the config lacks it, and
+    that is not the same as having none: printing "0 sources" would say
+    something the version never said.
     """
     counted = [
         _counted(config.get("entities"), "entity", "entities"),
@@ -211,43 +224,17 @@ def _counted(items, singular: str, plural: str) -> str:
     return f"{count} {singular if count == 1 else plural}"
 
 
-def warn_if_the_push_takes_the_sources_out_of_the_config(remote_config: dict) -> None:
-    """Say it when this push drops a `sources` key the connector has.
-
-    A directory with no `sources/` sends a config with no `sources` key, and
-    that is not "this connector has no sources": it is the switch that hands
-    the source definitions back to being managed outside the config. A
-    directory pulled before the sources were part of it flips that switch on
-    the next push, silently and with a zero exit code, which is why the one
-    push that does it says so.
-    """
-    if remote_config.get("sources") is None:
-        return
-    console.print(
-        "[yellow]The connector's draft declares 'sources' and this directory "
-        "does not, so this push takes the source definitions out of the "
-        "config: they go back to being managed outside it, and a later publish "
-        "leaves them alone. Run 'plugsync pull' first if you meant to keep them "
-        "in the directory.[/yellow]"
-    )
-
-
-def _expected_draft_version(
-    client: PlugSyncClient, context: ConnectorContext, draft: dict | None = None
-) -> int:
+def _expected_draft_version(client: PlugSyncClient, context: ConnectorContext) -> int:
     """The draft version a write guards itself with.
 
     Normally the one recorded at pull time, which is what makes a concurrent
     edit detectable. A directory pulled with `--revision` has none: there the
     current draft version is read now, which still rules out a write racing this
     command, and the weaker guarantee is stated out loud rather than assumed.
-
-    `draft` is the remote draft when the caller has already read it, so the two
-    reasons this function's caller has to fetch it cost one request, not two.
     """
     if context.draft_version is not None:
         return context.draft_version
-    current = (draft or client.get_draft(context.connector_id))["draft_version"]
+    current = client.get_draft(context.connector_id)["draft_version"]
     console.print(
         f"[yellow]This directory was pulled from a published version, not the "
         f"draft: guarding against edits after draft v{current} only.[/yellow]"

plugsync_cli/serializer.py

@@ -62,23 +62,25 @@ LOCAL_STATE_FILE_NAME = ".plugsync.yaml"
 # in plugsync.yaml, mapped to the directory that holds them.
 COLLECTION_DIRS = {"entities": "entities", "flows": "flows", "sources": "sources"}
 
-# Collections whose ABSENCE means something other than "empty".
+# Collections whose ABSENCE is not the same as "empty".
 #
-# `sources` is optional in the config (ADR-0026): a config with no `sources`
-# key leaves the connector on the path where the event source rows are
-# authoritative, while `sources: []` declares "this connector has no sources"
-# and makes the config the authority for them. The switch is per connector and
-# lives in the presence of the key, so the directory has to carry it: the
-# `sources/` directory exists exactly when the key does, empty directory
-# included. Materializing `sources: []` for a config that simply has no key --
-# the way `entities` and `flows` are materialized, where absent and empty are
-# the same thing -- would flip that switch on every pull.
+# `sources` is a mandatory key of the config (ADR-0026): `sources: []` declares
+# "this connector has no sources", and the API refuses a draft write that
+# omits the key, because read as "no sources" the omission would delete every
+# source the connector has at the next publish. The directory declares the key
+# through the `sources/` directory, empty directory included.
+#
+# So a directory with neither `sources/` nor an inline `sources` key is
+# refused on read (see `undeclared_collection_message`). Materializing
+# `sources: []` for it -- the way `entities` and `flows` are materialized,
+# where absent and empty are the same thing -- would turn "the directory is
+# missing" into "delete all my sources". The CLI stops instead of guessing.
 OPTIONAL_COLLECTIONS = frozenset({"sources"})
 
 # Written into an optional collection's directory when it holds no item, because
 # git carries no empty directory and the directory is what declares the key:
-# without it, pull -> commit -> clone -> push would drop `sources: []` and put
-# the connector back on the legacy path with a zero exit code.
+# without it, pull -> commit -> clone -> push would find no `sources/` and
+# refuse a directory that declared `sources: []` when it was pulled.
 DIRECTORY_KEEP_FILE = ".gitkeep"
 
 # Characters kept as-is in a file name. Entity and flow names are free-form
@@ -94,6 +96,25 @@ class ConfigDirectoryError(Exception):
     """The local directory is not a readable connector config."""
 
 
+def undeclared_collection_message(connector_dir: Path, key: str) -> str:
+    """What to do about a directory that does not declare `key` at all.
+
+    Shared by the local refusal in `read_config_directory` and by the
+    translation of the API's own refusal of the same thing, so the operator
+    reads one explanation whichever of the two catches it.
+    """
+    dir_name = COLLECTION_DIRS[key]
+    return (
+        f"{connector_dir} does not declare '{key}': there is no {dir_name}/ "
+        f"directory and no '{key}' key in {CONFIG_FILE_NAME}. Pushing it would "
+        f"ask the server to drop the connector's {key}, which it refuses. "
+        f"Run 'plugsync pull' to realign the directory with the draft; or "
+        f"create {dir_name}/ with an empty {DIRECTORY_KEEP_FILE} (and one file "
+        f"per {key[:-1]}) if you keep them as files; or write '{key}: []' in "
+        f"{CONFIG_FILE_NAME} if the connector really has no {key}."
+    )
+
+
 _TIMESTAMP_TAG = "tag:yaml.org,2002:timestamp"
 
 
@@ -317,7 +338,9 @@ def canonical_config(config: dict) -> dict:
     empty, so a config read from disk and one read from the API can be compared
     for equality (what `plugsync diff`, `validate` and `preview` do to tell
     local files from the remote draft). An optional collection the config does
-    not declare stays undeclared: see `OPTIONAL_COLLECTIONS`.
+    not declare stays undeclared: a version published before the sources were
+    part of the config carries no `sources` key, and inventing `sources: []`
+    for it would describe that version as something it never said.
     """
     canonical = {k: v for k, v in config.items() if k not in COLLECTION_DIRS}
     for key in COLLECTION_DIRS:
@@ -399,12 +422,15 @@ def _write_collection(
 
 
 def _undeclare_collection(collection_dir: Path) -> None:
-    """Erase an optional collection the config no longer declares.
-
-    Its directory is what declares the key, so leaving an emptied one behind
-    would make the next read say `sources: []` for a config that says nothing
-    about sources at all. A directory holding files this format does not own
-    (a README, a note) is emptied of its own and left standing.
+    """Erase an optional collection the config does not declare.
+
+    Only a version published before the sources were part of the config
+    (`pull --revision`) comes without the key. Its directory is what declares
+    the key, so leaving an emptied one behind would make the next read say
+    `sources: []` for a version that says nothing about sources at all; without
+    it, the next read refuses the directory and says how to declare them. A
+    directory holding files this format does not own (a README, a note) is
+    emptied of its own and left standing.
     """
     if not collection_dir.is_dir():
         return
@@ -424,6 +450,9 @@ def read_config_directory(connector_dir: Path, *, report: Report | None = None)
     (see `Normalization`). Commands pass a printer: the CLI says what it
     changed instead of changing it quietly. Omitting it discards the notes,
     which is only ever right for a caller that has already been told.
+
+    A directory that does not declare an optional collection is refused: see
+    `OPTIONAL_COLLECTIONS`.
     """
     report = report or _ignore
     config_path = connector_dir / CONFIG_FILE_NAME
@@ -438,7 +467,7 @@ def read_config_directory(connector_dir: Path, *, report: Report | None = None)
             _read_inline_collection(config, key, dir_name, collection_dir)
             continue
         if key in OPTIONAL_COLLECTIONS and not collection_dir.is_dir():
-            continue
+            raise ConfigDirectoryError(undeclared_collection_message(connector_dir, key))
         items = [
             _load_yaml(path, report) for path in sorted(collection_dir.glob("*.yaml"))
         ] if collection_dir.is_dir() else []
@@ -479,10 +508,11 @@ def _read_inline_collection(
     if config[key] is None:
         # `sources:` with nothing after it. Not a declaration: read as an empty
         # list it would turn a config that says nothing about sources into one
-        # declaring the connector has none, and it would disagree with
-        # `canonical_config`, which treats null as absent on the same document.
-        del config[key]
-        return
+        # declaring the connector has none, which is the guess the CLI refuses
+        # to make for a missing `sources/` directory too.
+        raise ConfigDirectoryError(
+            undeclared_collection_message(collection_dir.parent, key)
+        )
     items = config[key]
     for item in items:
         _item_name(item, key, CONFIG_FILE_NAME)

{plugsync_cli-0.6.0.dist-info → plugsync_cli-0.8.0.dist-info}/METADATA

@@ -1,18 +1,16 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.6.0
+Version: 0.8.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
+License-Expression: LicenseRef-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
+Project-URL: Documentation, https://docs.plugsync.com/reference/cli/
+Project-URL: Terms of Service, https://plugsync.com/it/terms
 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
@@ -20,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: click>=8.1
 Requires-Dist: httpx>=0.27
 Requires-Dist: pyyaml>=6.0
@@ -28,6 +27,7 @@ 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"
+Dynamic: license-file
 
 # plugsync-cli
 
@@ -91,11 +91,13 @@ 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://docs.plugsync.com) and in the
-[plugsync repository](https://github.com/exelab/plugsync/tree/main/docs).
+[docs.plugsync.com](https://docs.plugsync.com).
 
 ## 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.
+Proprietary, not open source. The license to install and use this CLI is
+granted by paragraph 11.2 of the plugsync Terms of Service, published at
+[plugsync.com/it/terms](https://plugsync.com/it/terms): a non-exclusive,
+non-transferable, free-of-charge license, for the term of your plugsync
+agreement, solely for the purpose of using the plugsync service. The
+`LICENSE` file shipped with the package carries the full notice.

{plugsync_cli-0.6.0.dist-info → plugsync_cli-0.8.0.dist-info}/RECORD

@@ -1,26 +1,27 @@
-plugsync_cli/__init__.py,sha256=9pLbhLEWSNpmKOlVXv-RrmZ-SDMReErqgmTFQgJcKpY,75
+plugsync_cli/__init__.py,sha256=eDPwXO1lIo5lCvUfCDMdO6mSxWqST0tX30uKPMmCUWU,75
 plugsync_cli/bundler.py,sha256=nCskRqAILHe3LLMZSyS4klBbM879yBvVJODpZvEEm38,2219
-plugsync_cli/client.py,sha256=3AklXqJAtX4Jo6dk313-_f_oQFpawX2nUwUdaO-lFqM,15059
+plugsync_cli/client.py,sha256=k_hHOZG99MRwOPti9zCfniFzcIxCvatpBkodR1x3RRU,18402
 plugsync_cli/compat.py,sha256=DCN-DO8FVQDjTz3sgMW3JAjIAWNhplan4zibDnwjK9w,4106
 plugsync_cli/config.py,sha256=z2DntLCY1RPU5gcqdDgkJ97fRd18clsXTvAlzLLcz10,1888
-plugsync_cli/context.py,sha256=x9KFpP3LbxQ6u9dHPnx9VIqiuBer50G5IBzOPEXQNOI,11272
+plugsync_cli/context.py,sha256=5sk5_xkuL7LsE0fDitWVsKUArwx18Vyr47mgs-uMrUU,10624
 plugsync_cli/findings.py,sha256=ORWvqV7P8ss4Id846LZwWp5X6xEh7uZl6c86faDXfyQ,5526
 plugsync_cli/main.py,sha256=z_zM0GXm_tq_ZlNdFqlYuNQOk6cCdxsLagWmN95bAdw,3886
 plugsync_cli/schema_defaults.py,sha256=tSMmm9cjQlj2YvN7Q20s0rwoHjiOdH6CLttlfbLzmaE,8089
-plugsync_cli/serializer.py,sha256=AT4dibmjM6vNVq2cb6M-4uPTqd0q6KPRLDExS-uJXwo,23995
+plugsync_cli/serializer.py,sha256=Nspm510tbgwI_udiPpNeXjO_NVWL-T1VEC9uvpXYqMM,25620
 plugsync_cli/commands/__init__.py,sha256=wgYTWnZKXF-4M9ITNDhZMTUJH6_FthcUt_5zGj9NS8I,20
 plugsync_cli/commands/auth.py,sha256=cAcN8ALfkEOcejB4s4zq19dxS6v6iAw691B0HPTQd-Q,5590
-plugsync_cli/commands/connector.py,sha256=FzoK7P5m-siCUpYeFkXbCzimMU_UePmbaP-wqcM_DU0,8751
-plugsync_cli/commands/diff.py,sha256=k7KOay6k4h27Ru2eiaHsCbQyyqn50e6LbFJLkYfW1PY,19937
+plugsync_cli/commands/connector.py,sha256=_hmxZNMqP7XNo-DD3QreV39UzLr3oRKmLmKd3U0756E,25707
+plugsync_cli/commands/diff.py,sha256=zgTA5FeJLPnr-kiQaUezEyF5Wwq_2Gv4qnKnxvNkA7Q,19664
 plugsync_cli/commands/log.py,sha256=49GBgAvvs07d-OwMEgKKc7WalCKH2xmr5l7Ov6N13jM,3376
-plugsync_cli/commands/plugin.py,sha256=as1BM6lxpPcdrE12D--BCbSiriCLJbZED8utqJIGos8,20018
+plugsync_cli/commands/plugin.py,sha256=ziLaciAVFTCQp18-mwIYaPriWhKR1zWS0Pldxsjp6OQ,20672
 plugsync_cli/commands/preview.py,sha256=7MyGDqyb_6XLiO6-CFyNJDBuD2BXqfKg8Y2U3ax2ptM,2960
 plugsync_cli/commands/pull.py,sha256=UXXaINuTHo3sroXAmfA7BZFQj7eG8OKrWCbvhu1Y05o,2479
-plugsync_cli/commands/push.py,sha256=49X7PeveY3oEWb3HrCKRzeqKKAdQGrbXcv9Yiz4y8Ag,5081
+plugsync_cli/commands/push.py,sha256=xZNpRY4wAcTnkkw59Tg18lRoYilFCC-t8SR1RvC5CQA,6520
 plugsync_cli/commands/rollback.py,sha256=OtBk4U7yZubNVwhRmtyX0tSl20oWq8Pcy1Apjj_Ep-0,2471
 plugsync_cli/commands/validate.py,sha256=1ZjGSSkb21_2URmlyNaBBZXh-MI4L6cU_biKwJ6Itr4,1670
-plugsync_cli-0.6.0.dist-info/METADATA,sha256=tMq39rER6FCGqCsaV5W7wDOIFrCw6u-Eh62K8BtjJBo,4377
-plugsync_cli-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-plugsync_cli-0.6.0.dist-info/entry_points.txt,sha256=qWyWFQxY9W7L0hEwoDFjQjgs7TxJMsETk2nIe8jCA9E,51
-plugsync_cli-0.6.0.dist-info/top_level.txt,sha256=tShdp15OlzUttfE_QlFMLIfwQfImdp4YVhmB5rXZCgA,13
-plugsync_cli-0.6.0.dist-info/RECORD,,
+plugsync_cli-0.8.0.dist-info/licenses/LICENSE,sha256=5op7H-LOvR3Worm5Caabx48Er2AUe8Kp0eLCJoIoCYQ,1598
+plugsync_cli-0.8.0.dist-info/METADATA,sha256=QwLX7YQd-W1Ty6bn_phSiXNYbREgIOsihAzQg5N7O-o,4466
+plugsync_cli-0.8.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+plugsync_cli-0.8.0.dist-info/entry_points.txt,sha256=qWyWFQxY9W7L0hEwoDFjQjgs7TxJMsETk2nIe8jCA9E,51
+plugsync_cli-0.8.0.dist-info/top_level.txt,sha256=tShdp15OlzUttfE_QlFMLIfwQfImdp4YVhmB5rXZCgA,13
+plugsync_cli-0.8.0.dist-info/RECORD,,

plugsync_cli-0.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,35 @@
+plugsync-cli
+Copyright (c) 2026 Exelab S.r.l. All rights reserved.
+
+This package is the plugsync command-line interface (the "CLI"), client
+software distributed by Exelab S.r.l. ("Exelab") for use with the plugsync
+service. It is not open source software.
+
+The right to install and use the CLI is granted by paragraph 11.2 of the
+plugsync Terms of Service (the "Terms"), published at:
+
+    https://plugsync.com/it/terms
+
+Paragraph 11.2 of the Terms reads:
+
+    11.2 Software client. Per la durata del Contratto Exelab concede al
+    Cliente una licenza non esclusiva, non trasferibile e gratuita di
+    installare e utilizzare la CLI e il Server MCP al solo fine di utilizzare
+    il Servizio, nel rispetto dell'Articolo 6.
+
+    (Courtesy translation: For the term of the Agreement, Exelab grants the
+    Customer a non-exclusive, non-transferable, free-of-charge license to
+    install and use the CLI and the MCP Server solely for the purpose of using
+    the Service, in compliance with Article 6.)
+
+No other right is granted. Exelab remains the sole owner of the CLI and of
+every intellectual property right in it (paragraph 11.1 of the Terms).
+Warranties and liability are governed by the Terms. Capitalised words have
+the meaning given to them in the Terms.
+
+The Terms are drafted in Italian, which is the authoritative text; any
+translation, including the one above, is provided as a courtesy only. Where
+this notice and the Terms differ, the Terms prevail.
+
+Third-party components that the CLI depends on are distributed under their
+own open source licenses, which continue to govern them.