plugsync-cli 0.5.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.5.0"
+__version__ = "0.7.0"

plugsync_cli/commands/diff.py

@@ -51,15 +51,21 @@ from typing import Any
 
 import click
 from rich.console import Console
+from rich.markup import escape
 from rich.table import Table
 
 from plugsync_cli.context import build_client, fail, load_context
 from plugsync_cli.schema_defaults import SchemaNode, plugin_embedded_fields, schema_root
+from plugsync_cli.serializer import OPTIONAL_COLLECTIONS
 
 console = Console()
 
 # Top-level config keys compared item-by-item (keyed by name) rather than whole.
-COLLECTIONS = {"entities": "entity", "flows": "flow"}
+# `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. 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
 # tell an operator where to look, and forty paths in a table cell do not.
@@ -198,6 +204,7 @@ def _diff_configs(local: dict, remote: dict, root: SchemaNode) -> list[dict]:
 
     for key, label in COLLECTIONS.items():
         member = root.child(key).item()
+        changes.extend(_declaration_change(key, local, remote))
         local_items, remote_items = _by_name(local.get(key)), _by_name(remote.get(key))
         for name in sorted(set(local_items) | set(remote_items)):
             if name not in remote_items:
@@ -228,6 +235,30 @@ def _diff_configs(local: dict, remote: dict, root: SchemaNode) -> list[dict]:
     return changes
 
 
+def _declaration_change(key: str, local: dict, remote: dict) -> list[dict]:
+    """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 or remote.get(key) is not None:
+        return []
+    return [
+        _simple(
+            f"{key}_key_added",
+            key,
+            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}",
+        )
+    ]
+
+
 def _simple(change_type: str, scope: str, detail: str) -> dict:
     return {
         "type": change_type,
@@ -264,7 +295,12 @@ def _table(changes: list[dict]) -> Table:
     # name -- which is the part this column exists to show.
     table.add_column("Detail", overflow="fold")
     for change in changes:
-        table.add_row(_mark(change["type"]), change["scope"], change["detail"])
+        # escape: item names and key paths come from the config, and one in
+        # brackets is valid rich markup that would be read as a style tag and
+        # swallowed, taking the name this column exists to show with it.
+        table.add_row(
+            _mark(change["type"]), escape(change["scope"]), escape(change["detail"])
+        )
     return table
 
 

plugsync_cli/commands/preview.py

@@ -1,6 +1,7 @@
 """plugsync preview -- what publishing the draft would change."""
 import click
 from rich.console import Console
+from rich.markup import escape
 from rich.table import Table
 
 from plugsync_cli.context import (
@@ -55,11 +56,18 @@ def preview(path: str | None):
         console.print(f"\n[bold]Publishing would apply {len(changes)} change(s)[/bold]\n")
         table = Table(show_header=True, header_style="bold")
         table.add_column("Change", width=24)
-        table.add_column("Detail")
+        # fold, and escape below: a change detail carries the key path the
+        # server names it by, and a name in brackets (`sources[hubspot].config`)
+        # is both valid rich markup, which would swallow the name, and one
+        # unbreakable word, which ellipsizing would cut at the wrong end.
+        table.add_column("Detail", overflow="fold")
         for change in changes:
-            scope = change.get("entity") or change.get("event_flow") or ""
-            detail = change.get("detail", "")
-            table.add_row(_mark(change.get("type", "unknown")), f"[bold]{scope}[/bold] {detail}" if scope else detail)
+            scope = escape(str(change.get("entity") or change.get("event_flow") or ""))
+            detail = escape(str(change.get("detail", "")))
+            table.add_row(
+                _mark(change.get("type", "unknown")),
+                f"[bold]{scope}[/bold] {detail}" if scope else detail,
+            )
         console.print(table)
 
     render_preflight(console, client.preflight(context.connector_id))

plugsync_cli/commands/pull.py

@@ -4,7 +4,12 @@ from pathlib import Path
 import click
 from rich.console import Console
 
-from plugsync_cli.context import build_client, fail, warn_if_flow_order_is_not_preserved
+from plugsync_cli.context import (
+    build_client,
+    describe_config,
+    fail,
+    warn_if_flow_order_is_not_preserved,
+)
 from plugsync_cli.serializer import write_config_directory, write_local_state
 
 console = Console()
@@ -61,10 +66,5 @@ def pull(connector_name: str, revision: int | None, output: str | None):
 
     warn_if_flow_order_is_not_preserved(config)
 
-    entities = len(config.get("entities") or [])
-    flows = len(config.get("flows") or [])
     console.print(f"[green]Pulled {state['source']} to {output_dir}/[/green]")
-    console.print(
-        f"  {entities} entit{'y' if entities == 1 else 'ies'}, "
-        f"{flows} flow{'' if flows == 1 else 's'}"
-    )
+    console.print(f"  {describe_config(config)}")

plugsync_cli/commands/push.py

@@ -9,7 +9,13 @@ config to production as a side effect of saving a file (#1241).
 import click
 from rich.console import Console
 
-from plugsync_cli.context import build_client, fail, load_context, write_draft_from_directory
+from plugsync_cli.context import (
+    build_client,
+    describe_config,
+    fail,
+    load_context,
+    write_draft_from_directory,
+)
 from plugsync_cli.findings import render_findings, render_preflight
 
 console = Console()
@@ -87,12 +93,9 @@ def push(
     console.print(f"Pushing [bold]{context.directory.name}[/bold] to the draft...")
     draft = write_draft_from_directory(client, context, force=force)
 
-    config = draft["config"]
-    entities = len(config.get("entities") or [])
-    flows = len(config.get("flows") or [])
     console.print(
         f"[green]Draft updated (draft v{draft['draft_version']}): "
-        f"{entities} entities, {flows} flows[/green]"
+        f"{describe_config(draft['config'])}[/green]"
     )
 
     if not do_publish:
@@ -134,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

@@ -9,17 +9,20 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import NoReturn
 
+import httpx
 from rich.console import Console
 
-from plugsync_cli.client import DraftConflict, PlugSyncClient
+from plugsync_cli.client import DraftConflict, PlugSyncClient, describe_http_error
 from plugsync_cli.serializer import (
     CONFIG_FILE_NAME,
     ConfigDirectoryError,
     Normalization,
     canonical_config,
     flows_sharing_a_trigger,
+    locate_in_directory,
     read_config_directory,
     read_local_state,
+    undeclared_collection_message,
     write_config_directory,
     write_local_state,
 )
@@ -128,10 +131,11 @@ def write_draft_from_directory(
     cosmetic: it is what `validate` and `preview` warn about, and a warning that
     fires every time stops being read exactly when it matters.
     """
+    config = context.config()
     expected_version = None if force else _expected_draft_version(client, context)
     try:
         draft = client.put_draft(
-            context.connector_id, context.config(), expected_version=expected_version
+            context.connector_id, config, expected_version=expected_version
         )
     except DraftConflict as conflict:
         fail(
@@ -139,6 +143,8 @@ def write_draft_from_directory(
             "it. Re-run 'plugsync pull' and reapply your changes, or "
             "'plugsync push --force' to overwrite theirs."
         )
+    except httpx.HTTPStatusError as 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"])
@@ -155,6 +161,69 @@ def write_draft_from_directory(
     return draft
 
 
+# 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
+    (`sources[hubspot].config.triggers[0].pattern`), which is not how the
+    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:
+        return message
+    lines = "\n".join(
+        f"  {file_name}: {key}" if key else f"  {file_name}" for file_name, key in located
+    )
+    return f"{message}\n\nIn your files:\n{lines}"
+
+
+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. 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"),
+        _counted(config.get("flows"), "flow", "flows"),
+    ]
+    if config.get("sources") is not None:
+        counted.append(_counted(config["sources"], "source", "sources"))
+    return ", ".join(counted)
+
+
+def _counted(items, singular: str, plural: str) -> str:
+    count = len(items or [])
+    return f"{count} {singular if count == 1 else plural}"
+
+
 def _expected_draft_version(client: PlugSyncClient, context: ConnectorContext) -> int:
     """The draft version a write guards itself with.
 

plugsync_cli/findings.py

@@ -8,6 +8,7 @@ severity therefore gets a glyph, a colour AND the literal word -- the word being
 the part that still reads correctly in a CI log with colour stripped.
 """
 from rich.console import Console
+from rich.markup import escape
 
 # severity -> (glyph, rich colour). Ordered worst-first: that is the order
 # findings are printed in, so the thing that blocks you is not below the noise.
@@ -34,13 +35,21 @@ def _summary(counts: dict[str, int]) -> str:
 
 
 def _render_one(console: Console, finding: dict) -> None:
+    """One finding, with everything the backend wrote printed verbatim.
+
+    `escape` on every backend-authored string: a finding names the key it is
+    about the way the config document does, and a name in brackets --
+    `sources[hubspot].config.triggers[0].pattern` -- is valid rich markup. Rich
+    read `[hubspot]` as a style tag and swallowed it, so the one word saying
+    WHICH source was wrong disappeared from the screen.
+    """
     severity = finding.get("severity", "info")
     # A severity this CLI does not know still gets printed, under its own name.
     glyph, colour = SEVERITY_STYLES.get(severity, ("?", "magenta"))
-    code = finding.get("code", "unknown")
+    code = escape(str(finding.get("code", "unknown")))
+    message = escape(str(finding.get("message", "")))
     console.print(
-        f"  [{colour}]{glyph} {severity:<7}[/{colour}] "
-        f"[bold]{code}[/bold]: {finding.get('message', '')}"
+        f"  [{colour}]{glyph} {severity:<7}[/{colour}] [bold]{code}[/bold]: {message}"
     )
     scope = finding.get("entity") or finding.get("event_flow")
     for label, value in (
@@ -49,7 +58,7 @@ def _render_one(console: Console, finding: dict) -> None:
         ("fix", finding.get("suggestion")),
     ):
         if value:
-            console.print(f"      [dim]{label}:[/dim] {value}")
+            console.print(f"      [dim]{label}:[/dim] {escape(str(value))}")
 
 
 def _severity_rank(severity: str) -> int:

plugsync_cli/serializer.py

@@ -1,15 +1,17 @@
 """Read and write a connector config v3 blob as a local directory.
 
 The directory IS the config: `plugsync.yaml` holds every top-level key except
-the two collections, which become one file per named item.
+the named collections, which become one file per item.
 
     connector-name/
     |-- plugsync.yaml        # version, settings, conflicts, pipelines, ...
     |-- entities/
     |   |-- contacts.yaml
     |   `-- orders.yaml
-    `-- flows/
-        `-- shop-order-created.yaml
+    |-- flows/
+    |   `-- shop-order-created.yaml
+    `-- sources/
+        `-- hubspot.yaml
 
 Serialization lives here, on the client, rather than behind a server-side
 export/import endpoint (issue #1241): draft and version are already JSON on
@@ -44,6 +46,7 @@ The config is a JSON document, so reading is also where a file stops being
 "whatever YAML built" and becomes "something JSON can carry" -- see
 `_ConfigLoader` and `_json_value` (issue #1254).
 """
+import re
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import date, datetime, time
@@ -57,7 +60,28 @@ LOCAL_STATE_FILE_NAME = ".plugsync.yaml"
 
 # Top-level config keys stored as a directory of named files instead of inline
 # in plugsync.yaml, mapped to the directory that holds them.
-COLLECTION_DIRS = {"entities": "entities", "flows": "flows"}
+COLLECTION_DIRS = {"entities": "entities", "flows": "flows", "sources": "sources"}
+
+# Collections whose ABSENCE is not the same as "empty".
+#
+# `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 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
 # strings server-side ("order.created", "shop/orders"), so anything else is
@@ -72,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"
 
 
@@ -291,12 +334,18 @@ def _load_yaml(path: Path, report: Report = _ignore) -> dict:
 def canonical_config(config: dict) -> dict:
     """The config as the directory format represents it.
 
-    Both collections present and sorted by name, 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).
+    Every collection sorted by name, and the mandatory ones present even when
+    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: 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:
+        if key in OPTIONAL_COLLECTIONS and config.get(key) is None:
+            continue
         items = config.get(key) or []
         canonical[key] = sorted(items, key=lambda item: _item_name(item, key, "config"))
     return canonical
@@ -323,27 +372,75 @@ def write_config_directory(output_dir: Path, config: dict) -> None:
     )
 
     for key, dir_name in COLLECTION_DIRS.items():
-        items = config.get(key) or []
         collection_dir = output_dir / dir_name
-        if not items and not collection_dir.is_dir():
+        declared = config.get(key)
+        optional = key in OPTIONAL_COLLECTIONS
+
+        if optional and declared is None:
+            _undeclare_collection(collection_dir)
+            continue
+        items = declared or []
+        if not items and not optional and not collection_dir.is_dir():
             continue
-        collection_dir.mkdir(exist_ok=True)
+        _write_collection(collection_dir, key, items, declares_itself=optional)
 
-        written: dict[str, str] = {}
-        for item in items:
-            name = _item_name(item, key, "config")
-            stem = _file_stem(name)
-            if stem in written:
-                raise ConfigDirectoryError(
-                    f"{key} {name!r} and {written[stem]!r} both map to the file "
-                    f"{stem}.yaml; rename one of them."
-                )
-            written[stem] = name
-            _write_yaml(collection_dir / f"{stem}.yaml", item)
 
-        for stale in collection_dir.glob("*.yaml"):
-            if stale.stem not in written:
-                stale.unlink()
+def _write_collection(
+    collection_dir: Path, key: str, items: list, *, declares_itself: bool
+) -> None:
+    """One file per named item, and nothing else this format owns.
+
+    `declares_itself` says that the existence of this directory is what tells
+    the reader the config declares the key at all, which is true of the
+    optional collections and only of those. It is what earns the empty
+    directory a `DIRECTORY_KEEP_FILE`, and what takes it away again as soon as
+    a real item is there to hold the directory up.
+    """
+    collection_dir.mkdir(exist_ok=True)
+
+    written: dict[str, str] = {}
+    for item in items:
+        name = _item_name(item, key, "config")
+        stem = _file_stem(name)
+        if stem in written:
+            raise ConfigDirectoryError(
+                f"{key} {name!r} and {written[stem]!r} both map to the file "
+                f"{stem}.yaml; rename one of them."
+            )
+        written[stem] = name
+        _write_yaml(collection_dir / f"{stem}.yaml", item)
+
+    for stale in collection_dir.glob("*.yaml"):
+        if stale.stem not in written:
+            stale.unlink()
+
+    keep_file = collection_dir / DIRECTORY_KEEP_FILE
+    if declares_itself and not items:
+        keep_file.touch()
+    elif keep_file.exists():
+        keep_file.unlink()
+
+
+def _undeclare_collection(collection_dir: Path) -> None:
+    """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
+    for path in collection_dir.glob("*.yaml"):
+        path.unlink()
+    keep_file = collection_dir / DIRECTORY_KEEP_FILE
+    if keep_file.exists():
+        keep_file.unlink()
+    if not any(collection_dir.iterdir()):
+        collection_dir.rmdir()
 
 
 def read_config_directory(connector_dir: Path, *, report: Report | None = None) -> dict:
@@ -353,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
@@ -360,16 +460,14 @@ def read_config_directory(connector_dir: Path, *, report: Report | None = None)
         raise ConfigDirectoryError(f"No {CONFIG_FILE_NAME} found in {connector_dir}")
 
     config = _load_yaml(config_path, report)
-    for key in COLLECTION_DIRS:
-        if key in config:
-            raise ConfigDirectoryError(
-                f"{CONFIG_FILE_NAME} declares {key!r} inline, but {key} live in "
-                f"the {COLLECTION_DIRS[key]}/ directory. Move them there, or "
-                "re-run 'plugsync pull'."
-            )
 
     for key, dir_name in COLLECTION_DIRS.items():
         collection_dir = connector_dir / dir_name
+        if key in config:
+            _read_inline_collection(config, key, dir_name, collection_dir)
+            continue
+        if key in OPTIONAL_COLLECTIONS and not collection_dir.is_dir():
+            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 []
@@ -380,6 +478,89 @@ def read_config_directory(connector_dir: Path, *, report: Report | None = None)
     return config
 
 
+def _read_inline_collection(
+    config: dict, key: str, dir_name: str, collection_dir: Path
+) -> None:
+    """A collection plugsync.yaml still carries as a top-level key.
+
+    For `entities` and `flows` that is always an editing mistake, and ignoring
+    it would push a draft with every one of them deleted.
+
+    For `sources` it is what a CLI older than the `sources/` directory (0.5.0
+    and earlier) leaves behind: those releases preserve the key verbatim, so
+    the list is read as it stands and the next write splits it into files. What
+    is refused is a directory carrying BOTH -- two lists of sources, of which a
+    push would send one and delete the other.
+    """
+    if key not in OPTIONAL_COLLECTIONS:
+        raise ConfigDirectoryError(
+            f"{CONFIG_FILE_NAME} declares {key!r} inline, but {key} live in "
+            f"the {dir_name}/ directory. Move them there, or "
+            "re-run 'plugsync pull'."
+        )
+    if collection_dir.is_dir():
+        raise ConfigDirectoryError(
+            f"{CONFIG_FILE_NAME} declares {key!r} inline and {dir_name}/ also "
+            f"exists: two lists of {key}, and a push replaces the whole draft "
+            f"with one of them. Delete the {key!r} key from {CONFIG_FILE_NAME} "
+            f"to keep {dir_name}/, or delete {dir_name}/ to keep the key."
+        )
+    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, 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)
+    config[key] = sorted(items, key=lambda item: item["name"])
+
+
+# How the backend names a key inside a named collection item when it refuses a
+# draft write: `sources[hubspot].config.triggers[0].pattern` (ADR-0026), the
+# same shape the entity and flow diffs use.
+#
+# The name arrives quoted from part of the API (`sources['hubspot'] is declared
+# twice`) and bare from the rest, so the quotes are stripped below rather than
+# matched here: they are characters no file name may hold, and leaving them in
+# mangled the path into `_hubspot_.yaml`, a file that does not exist.
+_ITEM_PATH = re.compile(
+    r"\b(" + "|".join(COLLECTION_DIRS) + r")\[([^\[\]]+)\](?:\.([\w.\[\]]+))?"
+)
+
+# What the quoting above wraps the name in. Stripped, never mangled: a name may
+# legitimately contain neither, so nothing real is lost.
+_NAME_QUOTES = "'\""
+
+
+def locate_in_directory(message: str) -> list[tuple[str, str]]:
+    """Every config path a backend message names, as `(file, key)` pairs.
+
+    The API rejects a config by the path the key has in the JSON document; the
+    operator has a DIRECTORY in front of them. Resolving
+    `sources[hubspot].config.triggers[0].pattern` to
+    `sources/hubspot.yaml` plus `config.triggers[0].pattern` is the difference
+    between a 422 they can act on and one they have to decode by hand -- and
+    the file name is mangled here exactly as `write_config_directory` mangles
+    it, so a source called `shop/eu` is pointed at the file that really holds
+    it.
+
+    Ordered as they appear in the message, each path reported once.
+    """
+    return list(
+        dict.fromkeys(
+            (
+                f"{COLLECTION_DIRS[collection]}/{_file_stem(name.strip(_NAME_QUOTES))}.yaml",
+                key.rstrip("."),
+            )
+            for collection, name, key in _ITEM_PATH.findall(message)
+        )
+    )
+
+
 def flows_sharing_a_trigger(config: dict) -> list[tuple[str, str, list[str]]]:
     """Flow groups whose relative execution order this format does not preserve.
 

{plugsync_cli-0.5.0.dist-info → plugsync_cli-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.5.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.5.0.dist-info → plugsync_cli-0.7.0.dist-info}/RECORD

@@ -1,26 +1,26 @@
-plugsync_cli/__init__.py,sha256=-DngLLWTSfZYifUzSXxi_knZCypjhnrBbvnwnvb-4HM,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=RsKFNuEpKINExjyU-fKng6IIR9L-x8tr4TiCRHgIazI,7810
-plugsync_cli/findings.py,sha256=V4A60XI2rtfLTFj7kpGJivVFiUfIhu50N3FdCGRnmbU,5005
+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=93l_C88PsCj1fPMZMSTLXMY_D-bfFgpvjsDWiWwwJaQ,17353
+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=9XR6heMWXv3PhBEP9yH2UvgVqBb5UeDXchAvIQhRwpU,17821
+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=yAgXnVsViyaHS8uk4akP7OgJEmCyFUmKSbeW2S0AhBs,2534
-plugsync_cli/commands/pull.py,sha256=UPD7riTKIo-bCiDqrW2v_Ipsb5AgOQxlOqsEeSvl7nU,2624
-plugsync_cli/commands/push.py,sha256=j8yGJ_1j6da_0Xz4UI6im2b3G3_SF8z8VfidPFrnCkg,5160
+plugsync_cli/commands/preview.py,sha256=7MyGDqyb_6XLiO6-CFyNJDBuD2BXqfKg8Y2U3ax2ptM,2960
+plugsync_cli/commands/pull.py,sha256=UXXaINuTHo3sroXAmfA7BZFQj7eG8OKrWCbvhu1Y05o,2479
+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.5.0.dist-info/METADATA,sha256=DxWUCgcZpDbbMo4RFKYLn5mO-LXxuioVzYONtzPfd4g,4377
-plugsync_cli-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-plugsync_cli-0.5.0.dist-info/entry_points.txt,sha256=qWyWFQxY9W7L0hEwoDFjQjgs7TxJMsETk2nIe8jCA9E,51
-plugsync_cli-0.5.0.dist-info/top_level.txt,sha256=tShdp15OlzUttfE_QlFMLIfwQfImdp4YVhmB5rXZCgA,13
-plugsync_cli-0.5.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,,