plugsync-cli 0.6.0__py3-none-any.whl → 0.7.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.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/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.7.0.dist-info}/METADATA

@@ -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.dist-info → plugsync_cli-0.7.0.dist-info}/RECORD

@@ -1,26 +1,26 @@
-plugsync_cli/__init__.py,sha256=9pLbhLEWSNpmKOlVXv-RrmZ-SDMReErqgmTFQgJcKpY,75
+plugsync_cli/__init__.py,sha256=PlGlt8CSRA3Ay-FfIqLXUuPNEOUwWaen2HnLvTWZukI,75
 plugsync_cli/bundler.py,sha256=nCskRqAILHe3LLMZSyS4klBbM879yBvVJODpZvEEm38,2219
 plugsync_cli/client.py,sha256=3AklXqJAtX4Jo6dk313-_f_oQFpawX2nUwUdaO-lFqM,15059
 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/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/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.7.0.dist-info/METADATA,sha256=0ME4zUbvMWbTXNShCGxCbFasqd4utL2z-mnrOWKs5AA,4377
+plugsync_cli-0.7.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+plugsync_cli-0.7.0.dist-info/entry_points.txt,sha256=qWyWFQxY9W7L0hEwoDFjQjgs7TxJMsETk2nIe8jCA9E,51
+plugsync_cli-0.7.0.dist-info/top_level.txt,sha256=tShdp15OlzUttfE_QlFMLIfwQfImdp4YVhmB5rXZCgA,13
+plugsync_cli-0.7.0.dist-info/RECORD,,