plugsync-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{plugsync_cli-0.6.0 → plugsync_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.6.0
+Version: 0.7.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

{plugsync_cli-0.6.0 → plugsync_cli-0.7.0}/plugsync_cli/__init__.py

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

{plugsync_cli-0.6.0 → plugsync_cli-0.7.0}/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-0.6.0 → plugsync_cli-0.7.0}/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-0.6.0 → plugsync_cli-0.7.0}/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-0.6.0 → plugsync_cli-0.7.0}/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 → plugsync_cli-0.7.0}/plugsync_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.6.0
+Version: 0.7.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

{plugsync_cli-0.6.0 → plugsync_cli-0.7.0}/pyproject.toml

@@ -11,7 +11,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plugsync-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "Command-line client for plugsync HubSpot connectors -- manage connectors and plugins like code, no repo checkout required"
 readme = "README.md"
 license = { text = "Proprietary" }

{plugsync_cli-0.6.0 → plugsync_cli-0.7.0}/tests/test_commands.py

@@ -9,6 +9,7 @@ against a real server is `test_e2e_draft_api.py`'s.
 import os
 
 import httpx
+import pytest
 import yaml
 from click.testing import CliRunner
 from unittest.mock import MagicMock, patch
@@ -28,6 +29,8 @@ CONFIG = {
     "flows": [
         {"name": "shop-orders", "source": "shop", "event_type": "order.created", "steps": []}
     ],
+    # Every draft the API answers declares the key (ADR-0026), `[]` included.
+    "sources": [],
 }
 
 
@@ -494,6 +497,55 @@ class TestPush:
         assert "envelope_like_path" in result.output
         assert "portal_unreachable" in result.output
 
+    def test_push_publish_reveals_the_secrets_of_the_sources_it_created(self, tmp_path):
+        """#1570 / UI-42: a `webhook` source declared in the draft is created
+        BY the publish, and `created_sources` is the one and only place its
+        plaintext secret appears. Swallowing it would leave the operator with a
+        live source and no usable secret."""
+        directory = _local_dir(tmp_path, "shop")
+        client = _mock_client()
+        client.publish.return_value = {
+            "version": 5,
+            "warnings": [],
+            "created_sources": [
+                {"name": "shop_hook", "secret": "whsec-0123456789abcdef"},
+                {"name": "erp_hook", "secret": "whsec-second-value"},
+                # No secret to generate: must not print a bare name with an
+                # empty value next to two real secrets.
+                {"name": "nightly_poller", "secret": None},
+            ],
+        }
+
+        runner = CliRunner()
+        with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
+            result = _run_ok(runner, ["push", str(directory), "--publish"])
+
+        out = _flat(result.output)
+        assert "whsec-0123456789abcdef" in out
+        assert "whsec-second-value" in out
+        assert "shop_hook" in out and "erp_hook" in out
+        assert "nightly_poller" not in out
+        assert "only once" in out.lower()
+        # Unrecoverable by design, so the warning has to name the way back.
+        assert "rotate" in out.lower()
+
+    def test_push_publish_says_nothing_when_no_source_carried_a_secret(self, tmp_path):
+        directory = _local_dir(tmp_path, "shop")
+        client = _mock_client()
+        client.publish.return_value = {
+            "version": 5,
+            "warnings": [],
+            "created_sources": [{"name": "nightly_poller", "secret": None}],
+        }
+
+        runner = CliRunner()
+        with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
+            result = _run_ok(runner, ["push", str(directory), "--publish"])
+
+        out = _flat(result.output).lower()
+        assert "published v5" in out
+        assert "secret" not in out
+
     def test_push_publish_refuses_on_a_preflight_error(self, tmp_path):
         directory = _local_dir(tmp_path, "shop")
         client = _mock_client()
@@ -905,6 +957,7 @@ class TestDiffNamesWhatChanged:
                 "steps": [{"id": "upsert", "action": "upsert", "target": "hubspot"}],
             }
         ],
+        "sources": [],
     }
 
     @staticmethod
@@ -929,6 +982,7 @@ class TestDiffNamesWhatChanged:
                     "steps": [step],
                 }
             ],
+            "sources": [],
         }
 
     def test_only_a_materialized_default_is_not_a_change_of_yours(self, tmp_path):
@@ -1014,6 +1068,7 @@ class TestDiffNamesWhatChanged:
                 }
             ],
             "flows": [],
+            "sources": [],
         }
 
     EMAIL = {"source": "$.payload.email", "target": "email"}
@@ -1221,6 +1276,7 @@ class TestDiffPluginEmbeddedFields:
                     "steps": [step],
                 }
             ],
+            "sources": [],
         }
 
     def _embedded_step(self, **overrides) -> dict:
@@ -1491,15 +1547,17 @@ SOURCES = [
 ]
 
 CONFIG_WITH_SOURCES = {**CONFIG, "sources": SOURCES}
+# A version published before the sources were part of the config: no key.
+CONFIG_BEFORE_SOURCES = {k: v for k, v in CONFIG.items() if k != "sources"}
 
 
 class TestSources:
     """The connector directory carries the sources too, losslessly.
 
-    The key is optional in the config and its absence is not an empty list: it
-    is the per-connector switch between "the event source rows are
-    authoritative" and "the config is". A pull that invented `sources: []`, or
-    a push that dropped the key, would flip that switch behind the operator.
+    Every draft declares the key (ADR-0026), `[]` included, and `[]` means
+    "this connector has no sources": the publish deletes whatever rows it had.
+    So a pull must not invent the key for a version that lacks it, and an
+    empty declaration must survive the round trip as an empty directory.
     """
 
     def test_pull_writes_one_file_per_source_and_counts_them(self, tmp_path):
@@ -1520,13 +1578,18 @@ class TestSources:
         assert yaml.safe_load((out / "sources" / "hubspot.yaml").read_text()) == SOURCES[0]
         assert "3 sources" in _flat(result.output)
 
-    def test_pull_says_nothing_about_sources_when_the_config_has_none(self, tmp_path):
+    def test_pull_says_nothing_about_sources_when_the_version_has_no_key(self, tmp_path):
+        """A version published before sources were versioned: "0 sources"
+        would say something that version never said."""
         client = _mock_client()
         client.find_connector.return_value = {"id": CONNECTOR_ID, "name": "shop"}
+        client.get_version.return_value = _version_response(1, CONFIG_BEFORE_SOURCES)
 
         runner = CliRunner()
         with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
-            result = _run_ok(runner, ["pull", "shop", "-o", str(tmp_path / "shop")])
+            result = _run_ok(
+                runner, ["pull", "shop", "--revision", "1", "-o", str(tmp_path / "shop")]
+            )
 
         assert not (tmp_path / "shop" / "sources").exists()
         assert "source" not in _flat(result.output).lower()
@@ -1557,16 +1620,6 @@ class TestSources:
 
         assert client.put_draft.call_args[0][1]["sources"] == []
 
-    def test_push_does_not_invent_the_key_for_a_directory_without_it(self, tmp_path):
-        directory = _local_dir(tmp_path, "shop")
-        client = _mock_client()
-
-        runner = CliRunner()
-        with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
-            _run_ok(runner, ["push", str(directory)])
-
-        assert "sources" not in client.put_draft.call_args[0][1]
-
     def test_a_rejected_source_is_reported_by_file_and_key(self, tmp_path):
         """A 422 names a path in the config; the operator sees a directory."""
         directory = _local_dir(tmp_path, "shop", config=CONFIG_WITH_SOURCES)
@@ -1683,100 +1736,162 @@ class TestSources:
         assert "sources[hubspot].config.triggers[0].pattern" in flat
 
 
-class TestSourcesKeyTransition:
-    """The `sources` key appearing or disappearing is a change in itself.
+def _undeclared_dir(tmp_path, name="shop"):
+    """A directory that declares no sources: no `sources/`, no inline key.
 
-    Compared item by item, "declared empty" and "not declared at all" look
-    identical: no sources on either side. They are not the same thing -- one
-    puts the definitions under the connector's config, the other leaves them
-    to whatever manages them outside it -- so the transition needs saying out
-    loud, in `diff` and on the push that performs it.
+    What a CLI 0.5.x pull without inline sources leaves behind, or a clone of
+    a repository where the `.gitkeep` holding up an empty `sources/` was lost.
     """
+    return _local_dir(tmp_path, name, config=CONFIG_BEFORE_SOURCES)
 
-    def test_diff_says_the_published_version_declares_sources_and_the_files_do_not(
-        self, tmp_path
-    ):
-        directory = _local_dir(tmp_path, "shop")
+
+def _assert_says_how_to_declare_the_sources(output: str, directory) -> None:
+    flat = _flat(output)
+    assert str(directory) in flat
+    assert "does not declare 'sources'" in flat
+    assert "plugsync pull" in flat
+    assert ".gitkeep" in flat
+    assert "sources: []" in flat
+
+
+class TestUndeclaredSources:
+    """A directory that does not declare `sources` stops in local (#1630).
+
+    The API refuses a draft write that omits the key (422
+    `sources_key_removal_not_supported`), and `sources: []` in its place would
+    delete every source at the next publish. So the CLI neither sends the
+    directory as it is nor fills the gap: it stops before any request and says
+    how to declare the sources.
+    """
+
+    @pytest.mark.parametrize(
+        "args",
+        [["push"], ["push", "--force"], ["validate"], ["validate", "--push"], ["preview"], ["diff"]],
+    )
+    def test_the_command_stops_before_touching_the_api(self, tmp_path, args):
+        directory = _undeclared_dir(tmp_path)
         client = _mock_client()
-        client.list_revisions.return_value = [{"version": 2, "is_active": True}]
-        client.get_version.return_value = _version_response(2, {**CONFIG, "sources": []})
 
         runner = CliRunner()
         with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
-            result = _run_ok(runner, ["diff", str(directory)])
+            result = runner.invoke(cli, [*args, str(directory)])
 
-        flat = _flat(result.output)
-        assert "sources_key_removed" in flat
-        assert "1 change detected" in flat
+        assert result.exit_code == 1, result.output
+        _assert_says_how_to_declare_the_sources(result.output, directory)
+        assert client.method_calls == []
+
+    def test_a_null_inline_key_is_refused_the_same_way(self, tmp_path):
+        directory = _undeclared_dir(tmp_path)
+        config_file = directory / "plugsync.yaml"
+        config_file.write_text(config_file.read_text() + "sources:\n")
+        client = _mock_client()
+
+        runner = CliRunner()
+        with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
+            result = runner.invoke(cli, ["push", str(directory)])
+
+        assert result.exit_code == 1
+        _assert_says_how_to_declare_the_sources(result.output, directory)
+        client.put_draft.assert_not_called()
 
-    def test_diff_says_the_files_declare_sources_and_the_published_version_does_not(
+    def test_a_sources_directory_holding_only_the_placeholder_sends_an_empty_list(
         self, tmp_path
     ):
-        directory = _local_dir(tmp_path, "shop", config={**CONFIG, "sources": []})
+        directory = _undeclared_dir(tmp_path)
+        (directory / "sources").mkdir()
+        (directory / "sources" / ".gitkeep").touch()
         client = _mock_client()
-        client.list_revisions.return_value = [{"version": 2, "is_active": True}]
-        client.get_version.return_value = _version_response(2, CONFIG)
 
         runner = CliRunner()
         with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
-            result = _run_ok(runner, ["diff", str(directory)])
+            _run_ok(runner, ["push", str(directory)])
 
-        assert "sources_key_added" in _flat(result.output)
+        assert client.put_draft.call_args[0][1]["sources"] == []
 
-    def test_diff_is_quiet_when_both_sides_declare_the_key(self, tmp_path):
-        directory = _local_dir(tmp_path, "shop", config={**CONFIG, "sources": []})
+    def test_inline_sources_written_by_a_0_5_cli_are_pushed_and_split_into_files(
+        self, tmp_path
+    ):
+        directory = _undeclared_dir(tmp_path)
+        config_file = directory / "plugsync.yaml"
+        inline = {**yaml.safe_load(config_file.read_text()), "sources": SOURCES}
+        config_file.write_text(yaml.dump(inline))
         client = _mock_client()
-        client.list_revisions.return_value = [{"version": 2, "is_active": True}]
-        client.get_version.return_value = _version_response(2, {**CONFIG, "sources": []})
+        client.put_draft.return_value = _draft_response(CONFIG_WITH_SOURCES, draft_version=4)
 
         runner = CliRunner()
         with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
-            result = _run_ok(runner, ["diff", str(directory)])
+            _run_ok(runner, ["push", str(directory)])
 
-        assert "sources_key" not in _flat(result.output)
+        sent = client.put_draft.call_args[0][1]
+        assert sent["sources"] == sorted(SOURCES, key=lambda s: s["name"])
+        assert (directory / "sources" / "hubspot.yaml").exists()
+        assert "sources" not in yaml.safe_load(config_file.read_text())
 
-    def test_push_warns_when_it_takes_the_key_off_the_connector(self, tmp_path):
-        """A directory predating `sources/` pushes the key away, silently."""
+    def test_the_servers_refusal_is_translated_into_the_directorys_terms(self, tmp_path):
+        """If the request goes out anyway, the 422 is not printed as JSON."""
         directory = _local_dir(tmp_path, "shop")
+        client = _mock_client(
+            put_draft=MagicMock(
+                side_effect=_http_error(
+                    422,
+                    {
+                        "detail": {
+                            "error": "sources_key_removal_not_supported",
+                            "message": "this draft declares 'sources', and the "
+                            "declaration cannot be withdrawn",
+                        }
+                    },
+                )
+            )
+        )
+
+        runner = CliRunner()
+        with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
+            result = runner.invoke(cli, ["push", str(directory)])
+
+        assert result.exit_code == 1
+        _assert_says_how_to_declare_the_sources(result.output, directory)
+        assert "sources_key_removal_not_supported" not in _flat(result.output)
+
+    def test_diff_never_reports_the_key_as_removed(self, tmp_path):
+        """The direction that drops the key is an error, not a change."""
+        directory = _undeclared_dir(tmp_path)
         client = _mock_client()
-        client.get_draft.return_value = _draft_response(CONFIG_WITH_SOURCES)
+        client.list_revisions.return_value = [{"version": 2, "is_active": True}]
+        client.get_version.return_value = _version_response(2, CONFIG)
 
         runner = CliRunner()
         with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
-            result = _run_ok(runner, ["push", str(directory)])
+            result = runner.invoke(cli, ["diff", str(directory)])
 
-        flat = _flat(result.output).lower()
-        assert "sources" in flat
-        assert "plugsync pull" in flat
+        assert result.exit_code == 1
+        assert "sources_key_removed" not in _flat(result.output)
 
-    def test_push_is_quiet_when_the_draft_declares_no_sources_either(self, tmp_path):
+    def test_diff_says_the_published_version_predates_the_sources(self, tmp_path):
+        """A version published before sources were versioned has no key; the
+        local files always declare it, so this is the one transition left."""
         directory = _local_dir(tmp_path, "shop")
         client = _mock_client()
+        client.list_revisions.return_value = [{"version": 2, "is_active": True}]
+        client.get_version.return_value = _version_response(2, CONFIG_BEFORE_SOURCES)
 
         runner = CliRunner()
         with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
-            result = _run_ok(runner, ["push", str(directory)])
-
-        assert "removes" not in _flat(result.output).lower()
+            result = _run_ok(runner, ["diff", str(directory)])
 
-    def test_push_reads_the_draft_once_when_it_has_to_read_it_at_all(self, tmp_path):
-        """The check costs one request, and only when it can fire.
+        assert "sources_key_added" in _flat(result.output)
 
-        A directory pulled from a published version already reads the draft for
-        its concurrency guard; the two must not become two round trips.
-        """
-        directory = _local_dir(
-            tmp_path,
-            "shop",
-            state={"connector": "shop", "connector_id": CONNECTOR_ID, "source": "version 2"},
-        )
+    def test_diff_is_quiet_when_both_sides_declare_the_key(self, tmp_path):
+        directory = _local_dir(tmp_path, "shop")
         client = _mock_client()
+        client.list_revisions.return_value = [{"version": 2, "is_active": True}]
+        client.get_version.return_value = _version_response(2, CONFIG)
 
         runner = CliRunner()
         with patch("plugsync_cli.context.PlugSyncClient", return_value=client):
-            _run_ok(runner, ["push", str(directory)])
+            result = _run_ok(runner, ["diff", str(directory)])
 
-        client.get_draft.assert_called_once_with(CONNECTOR_ID)
+        assert "sources_key" not in _flat(result.output)
 
     def test_push_reads_no_draft_when_the_directory_declares_sources(self, tmp_path):
         directory = _local_dir(tmp_path, "shop", config=CONFIG_WITH_SOURCES)
@@ -1788,21 +1903,21 @@ class TestSourcesKeyTransition:
 
         client.get_draft.assert_not_called()
 
-    def test_pull_revision_of_a_version_without_the_key_removes_the_directory(
+    def test_pull_revision_of_a_version_without_the_key_leaves_a_directory_push_refuses(
         self, tmp_path
     ):
         """Documented asymmetry: `pull --revision` + `push` is not `rollback`.
 
         A version published before the sources were part of the config carries
-        no key, and a pull SYNCS the directory to what it pulled. So the local
-        `sources/` goes, and pushing that directory would take the key off the
-        connector -- which `rollback`, restoring the whole blob into the draft,
-        does not do.
+        no key, and a pull SYNCS the directory to what it pulled, so the local
+        `sources/` goes. Pushing that directory would ask the server to drop
+        the key, so it is refused in local; `rollback`, restoring the whole
+        blob into the draft, is the way back to that version.
         """
         client = _mock_client()
         client.find_connector.return_value = {"id": CONNECTOR_ID, "name": "shop"}
         client.get_draft.return_value = _draft_response(CONFIG_WITH_SOURCES)
-        client.get_version.return_value = _version_response(1, CONFIG)
+        client.get_version.return_value = _version_response(1, CONFIG_BEFORE_SOURCES)
         out = tmp_path / "shop"
 
         runner = CliRunner()
@@ -1811,5 +1926,10 @@ class TestSourcesKeyTransition:
             assert (out / "sources").is_dir()
 
             _run_ok(runner, ["pull", "shop", "--revision", "1", "-o", str(out)])
+            assert not (out / "sources").exists()
 
-        assert not (out / "sources").exists()
+            result = runner.invoke(cli, ["push", str(out)])
+
+        assert result.exit_code == 1
+        _assert_says_how_to_declare_the_sources(result.output, out)
+        client.put_draft.assert_not_called()

{plugsync_cli-0.6.0 → plugsync_cli-0.7.0}/tests/test_e2e_draft_api.py

@@ -415,7 +415,15 @@ def test_second_pull_carries_a_deletion_made_elsewhere(live_backend, connector,
     assert [e["name"] for e in live_backend.get(draft_path)["config"]["entities"]] == ["contacts"]
 
     # Somebody else drops the entity, through the same API the dashboard uses.
-    live_backend.put(draft_path, {"version": "3.1", "entities": [], "flows": []})
+    # The `sources` declaration is carried over from the stored config rather
+    # than retyped: a body that omits the key on a draft that declares it is
+    # refused with `sources_key_removal_not_supported` (#1541), and this test
+    # is about the entity deletion, not about withdrawing the declaration.
+    stored = live_backend.get(draft_path)["config"]
+    edited = {"version": "3.1", "entities": [], "flows": []}
+    if "sources" in stored:
+        edited["sources"] = stored["sources"]
+    live_backend.put(draft_path, edited)
     assert live_backend.get(draft_path)["config"]["entities"] == []
 
     _run(runner, ["pull", connector["name"], "-o", str(workdir)])
@@ -629,19 +637,28 @@ def test_sources_survive_a_pull_push_round_trip(live_backend, connector, cli_env
 
     The round trip is the whole promise of `sources/`: an operator who pulls a
     connector and pushes it back untouched must end up with the draft they
-    started from, sources included. The `sources` key is also the per-connector
-    switch between "the event source rows are authoritative" and "the config
-    is" (ADR-0026), so a push that dropped it, or a pull that invented it,
-    would flip that switch behind their back.
+    started from, sources included. The `sources` key is mandatory in a draft
+    (ADR-0026), and `sources: []` deletes the connector's sources at publish,
+    so the empty declaration must travel as itself, never as a missing key.
+
+    Since #1541 a draft the backend materializes is born declaring the sources
+    the connector already has, which for a connector with no rows is the empty
+    declaration `sources: []`. The directory has to carry that distinction: an
+    EMPTY `sources/` directory means "declares zero sources", and the push must
+    send `sources: []` back rather than omit the key - omitting it is refused
+    with `sources_key_removal_not_supported`.
     """
     runner, workdir = cli_env, tmp_path / connector["name"]
     draft_path = f"/api/connectors/{connector['id']}/draft"
 
-    # A draft that has never declared sources stays that way through a pull.
+    # The empty declaration survives a pull as an empty directory, and a push
+    # sends it back as an empty list, not as an absent key.
     _run(runner, ["pull", connector["name"], "-o", str(workdir)])
-    assert not (workdir / "sources").exists()
+    assert live_backend.get(draft_path)["config"]["sources"] == []
+    assert (workdir / "sources").is_dir()
+    assert list((workdir / "sources").glob("*.yaml")) == []
     _run(runner, ["push", str(workdir)])
-    assert "sources" not in live_backend.get(draft_path)["config"]
+    assert live_backend.get(draft_path)["config"]["sources"] == []
 
     # Declare them as files, exactly as a config-as-code repo would.
     _write_sources(workdir, E2E_SOURCES)

{plugsync_cli-0.6.0 → plugsync_cli-0.7.0}/tests/test_hand_edited_yaml.py

@@ -57,6 +57,7 @@ def _read(tmp_path, plugsync_yaml: str, notes: list | None = None) -> dict:
     directory = tmp_path / "conn"
     directory.mkdir()
     (directory / "plugsync.yaml").write_text(plugsync_yaml)
+    (directory / "sources").mkdir()
     return read_config_directory(
         directory, report=None if notes is None else notes.append
     )

{plugsync_cli-0.6.0 → plugsync_cli-0.7.0}/tests/test_serializer.py

@@ -46,6 +46,8 @@ FULL_CONFIG = {
             "unknown_flow_key": ["kept"],
         }
     ],
+    # Mandatory in every config the API answers (ADR-0026).
+    "sources": [],
 }
 
 
@@ -82,8 +84,8 @@ def test_layout_is_one_readable_file_per_named_item(tmp_path):
     assert "flows" not in top_level
 
 
-def test_empty_config_round_trips_with_both_collections_present(tmp_path):
-    write_config_directory(tmp_path / "conn", {"version": "3.1"})
+def test_empty_config_round_trips_with_every_collection_present(tmp_path):
+    write_config_directory(tmp_path / "conn", {"version": "3.1", "sources": []})
 
     # An empty collection is not written as an empty directory (git would drop
     # it anyway), and reads back as the empty list the backend defaults to.
@@ -92,6 +94,7 @@ def test_empty_config_round_trips_with_both_collections_present(tmp_path):
         "version": "3.1",
         "entities": [],
         "flows": [],
+        "sources": [],
     }
 
 
@@ -141,6 +144,7 @@ def test_names_that_are_not_valid_filenames_still_round_trip(tmp_path):
         "version": "3.1",
         "entities": [{"name": "shop/orders v2", "schemas": {}}],
         "flows": [],
+        "sources": [],
     }
     write_config_directory(tmp_path / "conn", config)
 
@@ -195,6 +199,7 @@ def test_non_ascii_is_written_as_text_not_escapes(tmp_path):
         "version": "3.1",
         "settings": {"label": label},
         "entities": [{"name": "citta", "schemas": {}, "note": "perché sì"}],
+        "sources": [],
     }
     write_config_directory(tmp_path / "conn", config)
 
@@ -241,11 +246,12 @@ def test_missing_local_state_points_at_pull(tmp_path):
 
 
 # `sources` is the one collection whose ABSENCE is not an empty list (ADR-0026):
-# a config without the key leaves the connector on the path where the event
-# source rows are authoritative, `sources: []` declares "this connector has no
-# sources" and makes the config authoritative. The directory has to carry that
-# distinction, so it is the `sources/` directory itself that says the key is
-# declared.
+# `sources: []` declares "this connector has no sources", while a directory
+# that declares nothing is refused on read instead of guessed at -- the API
+# refuses a draft that omits the key, and `[]` in its place would delete every
+# source at the next publish. It is the `sources/` directory itself that says
+# the key is declared.
+WITHOUT_SOURCES = {k: v for k, v in FULL_CONFIG.items() if k != "sources"}
 THREE_SOURCES = [
     {"name": "hubspot", "type": "hubspot", "config": {"triggers": [{"property": "email"}]}},
     {"name": "shop", "type": "event_api", "config": {}},
@@ -273,13 +279,34 @@ class TestSources:
         top_level = yaml.safe_load((tmp_path / "conn" / "plugsync.yaml").read_text())
         assert "sources" not in top_level
 
-    def test_a_config_without_the_key_does_not_grow_one(self, tmp_path):
-        """Absence is the legacy switch: inventing `sources: []` would flip it."""
-        write_config_directory(tmp_path / "conn", FULL_CONFIG)
+    def test_a_version_without_the_key_does_not_grow_one(self, tmp_path):
+        """A version published before sources were versioned has no key.
+
+        Written as it is, and compared as it is: inventing `sources: []` for it
+        would describe it as declaring something it never said.
+        """
+        write_config_directory(tmp_path / "conn", WITHOUT_SOURCES)
 
         assert not (tmp_path / "conn" / "sources").exists()
-        assert "sources" not in read_config_directory(tmp_path / "conn")
-        assert "sources" not in canonical_config(FULL_CONFIG)
+        assert "sources" not in canonical_config(WITHOUT_SOURCES)
+
+    def test_a_directory_that_does_not_declare_the_sources_is_refused(self, tmp_path):
+        """No `sources/` and no inline key: stop, and say how to declare them.
+
+        Reading it as `sources: []` would turn "the directory is missing" into
+        "delete every source"; leaving the key out would earn a 422 from the
+        server that says nothing about the directory.
+        """
+        write_config_directory(tmp_path / "conn", WITHOUT_SOURCES)
+
+        with pytest.raises(ConfigDirectoryError) as refused:
+            read_config_directory(tmp_path / "conn")
+
+        message = str(refused.value)
+        assert str(tmp_path / "conn") in message
+        assert "plugsync pull" in message
+        assert "sources/" in message and ".gitkeep" in message
+        assert "sources: []" in message
 
     def test_an_empty_list_is_kept_apart_from_the_key_being_absent(self, tmp_path):
         write_config_directory(tmp_path / "conn", {**FULL_CONFIG, "sources": []})
@@ -287,11 +314,20 @@ class TestSources:
         assert (tmp_path / "conn" / "sources").is_dir()
         assert read_config_directory(tmp_path / "conn")["sources"] == []
 
+    def test_a_sources_directory_holding_only_the_placeholder_reads_empty(self, tmp_path):
+        """What a clone of a committed "no sources" directory looks like."""
+        conn = tmp_path / "conn"
+        write_config_directory(conn, WITHOUT_SOURCES)
+        (conn / "sources").mkdir()
+        (conn / "sources" / ".gitkeep").touch()
+
+        assert read_config_directory(conn)["sources"] == []
+
     def test_an_empty_sources_directory_survives_a_commit(self, tmp_path):
         """git carries no empty directory, and the directory IS the key here.
 
-        Without a file in it, pull -> commit -> clone -> push would silently
-        drop the key and put the connector back on the legacy path.
+        Without a file in it, pull -> commit -> clone -> push would find no
+        `sources/` and refuse a directory that declared `sources: []`.
         """
         write_config_directory(tmp_path / "conn", {**FULL_CONFIG, "sources": []})
 
@@ -316,14 +352,16 @@ class TestSources:
             "hubspot"
         ]
 
-    def test_dropping_the_key_removes_the_directory(self, tmp_path):
-        """Otherwise the next read would declare the key the config no longer has."""
+    def test_writing_a_version_without_the_key_removes_the_directory(self, tmp_path):
+        """Otherwise the next read would declare `sources: []` for a version
+        that says nothing about sources; without it, the read refuses instead."""
         write_config_directory(tmp_path / "conn", {**FULL_CONFIG, "sources": THREE_SOURCES})
 
-        write_config_directory(tmp_path / "conn", FULL_CONFIG)
+        write_config_directory(tmp_path / "conn", WITHOUT_SOURCES)
 
         assert not (tmp_path / "conn" / "sources").exists()
-        assert "sources" not in read_config_directory(tmp_path / "conn")
+        with pytest.raises(ConfigDirectoryError, match="does not declare 'sources'"):
+            read_config_directory(tmp_path / "conn")
 
     def test_sources_written_inline_by_an_older_cli_are_read(self, tmp_path):
         """0.5.0 and earlier round-trip `sources` as an opaque top-level key."""
@@ -360,22 +398,19 @@ class TestSources:
         with pytest.raises(ConfigDirectoryError, match="sources/"):
             read_config_directory(conn)
 
-    def test_a_null_key_reads_as_an_absent_one(self, tmp_path):
+    def test_a_null_key_is_refused_like_an_absent_one(self, tmp_path):
         """`sources:` with nothing after it is not a declaration.
 
         Read as an empty list it would turn a config that says nothing about
-        sources into one that declares the connector has none, which is the
-        opposite meaning. `canonical_config` already treats null as absent, so
-        reading it as `[]` also made the two disagree on the same document.
+        sources into one that declares the connector has none: the same guess
+        the CLI refuses to make for a missing `sources/` directory.
         """
         conn = tmp_path / "conn"
         conn.mkdir()
         (conn / "plugsync.yaml").write_text("version: '3.1'\nsources:\n")
 
-        config = read_config_directory(conn)
-
-        assert "sources" not in config
-        assert "sources" not in canonical_config(config)
+        with pytest.raises(ConfigDirectoryError, match="does not declare 'sources'"):
+            read_config_directory(conn)
 
     def test_an_unnamed_source_file_is_refused(self, tmp_path):
         conn = tmp_path / "conn"