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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.4.0
+Version: 0.6.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
@@ -75,6 +75,8 @@ override the config file, handy for CI.
 | `plugsync preview <name>` | Preview a publish's effects and its preflight findings |
 | `plugsync log <name>` | Show a connector's published version history |
 | `plugsync rollback <name>` | Restore a published version into the draft |
+| `plugsync connector breakers <name>` | List the connector's flows whose circuit breaker is open |
+| `plugsync connector flow retry <name> <flow>` | Retry one blocked flow now, instead of waiting for its automatic attempt |
 | `plugsync plugin init/push/list/status/logs/metrics/invoke/promote/publish/rollback` | Author and manage plugins (Enterprise tier) |
 
 Run `plugsync --help` or `plugsync <command> --help` for the full option list.

{plugsync_cli-0.4.0 → plugsync_cli-0.6.0}/README.md

@@ -44,6 +44,8 @@ override the config file, handy for CI.
 | `plugsync preview <name>` | Preview a publish's effects and its preflight findings |
 | `plugsync log <name>` | Show a connector's published version history |
 | `plugsync rollback <name>` | Restore a published version into the draft |
+| `plugsync connector breakers <name>` | List the connector's flows whose circuit breaker is open |
+| `plugsync connector flow retry <name> <flow>` | Retry one blocked flow now, instead of waiting for its automatic attempt |
 | `plugsync plugin init/push/list/status/logs/metrics/invoke/promote/publish/rollback` | Author and manage plugins (Enterprise tier) |
 
 Run `plugsync --help` or `plugsync <command> --help` for the full option list.

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

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

{plugsync_cli-0.4.0 → plugsync_cli-0.6.0}/plugsync_cli/client.py

@@ -1,5 +1,6 @@
 """HTTP client wrapper for PluSync REST API."""
 import json
+from urllib.parse import quote
 
 import httpx
 
@@ -120,6 +121,30 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
+    def retry_flow(self, connector_id: str, flow_name: str) -> dict:
+        """Retry one flow whose circuit breaker is open, returning the
+        refreshed connector.
+
+        The API moves the breaker to `half_open`, which makes the next message
+        through that flow the recovery probe: it is not a close, and a failed
+        probe re-opens the breaker with a longer cooldown. Idempotent when the
+        breaker is already half-open; 404 when the flow has no open breaker at
+        all, which the command translates into "nothing to retry".
+
+        The flow name is a config value, not a URL-safe token, so it is quoted
+        with no safe characters: a flow called `orders/eu` has to reach the API
+        as one path segment rather than two.
+        """
+        with self._client() as c:
+            r = c.post(
+                self._url(
+                    f"/connectors/{connector_id}/flows/"
+                    f"{quote(flow_name, safe='')}/retry"
+                )
+            )
+            r.raise_for_status()
+            return r.json()
+
     def get_draft(self, connector_id: str) -> dict:
         """The connector's editable config (backend DraftResponse).
 

plugsync_cli-0.6.0/plugsync_cli/commands/connector.py

@@ -0,0 +1,253 @@
+"""plugsync connector -- read a connector's flow circuit breakers, retry one.
+
+Self-service only, with the same org-scoped auth as every other command: the
+owner of a connector lists the flows whose circuit breaker is open and retries
+one of them, from a script or from CI, without opening the dashboard. The
+platform-side force-close is a different operation with a different
+authentication contract (it refuses an org API key) and deliberately has no
+command here.
+"""
+import uuid
+from datetime import datetime, timezone
+
+import click
+import httpx
+from rich.console import Console
+from rich.table import Table
+
+from plugsync_cli.client import PlugSyncClient
+from plugsync_cli.context import build_client, fail
+
+console = Console()
+
+_CONNECTOR_NOT_FOUND = (
+    "Connector '{label}' not found, or it does not belong to this organization."
+)
+
+
+def _looks_like_a_connector_id(reference: str) -> bool:
+    try:
+        uuid.UUID(reference)
+    except ValueError:
+        return False
+    return True
+
+
+def _resolve_connector(client: PlugSyncClient, reference: str) -> tuple[str, str]:
+    """A connector reference (name or id) as `(connector_id, label)`.
+
+    A UUID is taken as the id and used as-is: resolving it through the
+    connector listing would cost a round trip to learn a name the endpoints
+    already return in their own response.
+    """
+    if _looks_like_a_connector_id(reference):
+        return reference, reference
+    connector = client.find_connector(reference)
+    if not connector:
+        fail(f"Connector '{reference}' not found")
+    return connector["id"], connector.get("name") or reference
+
+
+def _detail(exc: httpx.HTTPStatusError) -> str:
+    """The API's `detail` string, or "" when the body carries none."""
+    try:
+        payload = exc.response.json()
+    except ValueError:
+        return ""
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    return detail if isinstance(detail, str) else ""
+
+
+def _open_breakers(connector: dict) -> list[dict]:
+    """The connector's non-closed flow breakers, one shape for two payloads.
+
+    `health.flows` is the richer form and the one to read. An API that predates
+    it answers only the legacy list, which carries the same flows under other
+    key names: normalizing it here keeps such a backend from reading as a
+    connector with nothing blocked.
+    """
+    flows = (connector.get("health") or {}).get("flows")
+    if flows:
+        return flows
+    return [
+        {
+            "name": flow.get("flow_name"),
+            "state": flow.get("state"),
+            "detail": flow.get("reason"),
+            "opened_at": flow.get("tripped_at"),
+        }
+        for flow in connector.get("tripped_flows") or []
+    ]
+
+
+def _breaker_for(connector: dict, flow_name: str) -> dict | None:
+    for breaker in _open_breakers(connector):
+        if breaker.get("name") == flow_name:
+            return breaker
+    return None
+
+
+def _reason(breaker: dict) -> str:
+    """The human-readable diagnostic, falling back to the machine code."""
+    return str(breaker.get("detail") or breaker.get("reason") or "")
+
+
+def _relative(value, *, now: datetime | None = None) -> str:
+    """An ISO timestamp as a short relative time, past or future.
+
+    Both directions matter in one table: a breaker opened in the past, and a
+    cooldown that expires in the future. An unparseable value is printed as it
+    arrived rather than dropped.
+    """
+    if not value:
+        return ""
+    try:
+        moment = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return str(value)
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+
+    delta = (moment - (now or datetime.now(timezone.utc))).total_seconds()
+    seconds = int(abs(delta))
+    if seconds < 60:
+        return "now"
+    if seconds < 3600:
+        magnitude = f"{seconds // 60}m"
+    elif seconds < 86400:
+        magnitude = f"{seconds // 3600}h"
+    else:
+        magnitude = f"{seconds // 86400}d"
+    return f"in {magnitude}" if delta > 0 else f"{magnitude} ago"
+
+
+@click.group()
+def connector():
+    """Inspect a connector's operational state."""
+    pass
+
+
+@connector.group()
+def flow():
+    """Act on one event flow of a connector."""
+    pass
+
+
+@flow.command("retry")
+@click.argument("connector_reference", metavar="CONNECTOR")
+@click.argument("flow_name", metavar="FLOW")
+def flow_retry(connector_reference: str, flow_name: str):
+    """Retry a flow whose circuit breaker is open.
+
+    CONNECTOR is a connector name or id, FLOW the event flow name. The breaker
+    moves to half-open: the next message through the flow is the recovery
+    probe. It is not a force-close, and a failed probe re-opens the breaker
+    with a longer cooldown.
+
+    Examples:
+        plugsync connector flow retry my-connector shop-orders
+    """
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+
+    try:
+        updated = client.retry_flow(connector_id, flow_name)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code != 404:
+            raise
+        if "connector not found" in _detail(exc).lower():
+            fail(_CONNECTOR_NOT_FOUND.format(label=label))
+        fail(
+            f"Flow '{flow_name}' has no open circuit breaker on '{label}': "
+            f"nothing to retry. Run 'plugsync connector breakers {label}' to "
+            "list the flows that are blocked."
+        )
+
+    name = updated.get("name") or label
+    breaker = _breaker_for(updated, flow_name)
+    if breaker is None:
+        console.print(
+            f"Retry accepted for flow '{flow_name}' on connector '{name}', but "
+            "the flow no longer appears among its open circuit breakers: there "
+            "is no breaker state left to report.",
+            soft_wrap=True,
+        )
+        return
+
+    state = breaker.get("state") or "unknown"
+    console.print(
+        f"[green]Flow '{flow_name}' on connector '{name}': breaker is now "
+        f"{state}.[/green]",
+        soft_wrap=True,
+    )
+    if state == "half_open":
+        console.print(
+            "The next message through this flow is the recovery probe: if it "
+            "succeeds the breaker closes, if it fails the breaker re-opens "
+            "with a longer cooldown.",
+            soft_wrap=True,
+        )
+
+
+@connector.command("breakers")
+@click.argument("connector_reference", metavar="CONNECTOR")
+def connector_breakers(connector_reference: str):
+    """List the flows of a connector whose circuit breaker is open.
+
+    CONNECTOR is a connector name or id. Read-only, and always exits 0 when it
+    could read the connector: a blocked flow is not a command failure.
+
+    Examples:
+        plugsync connector breakers my-connector
+    """
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+
+    try:
+        data = client.get_connector(connector_id)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code != 404:
+            raise
+        fail(_CONNECTOR_NOT_FOUND.format(label=label))
+
+    name = data.get("name") or label
+    breakers = _open_breakers(data)
+    if not breakers:
+        console.print(f"[green]No open circuit breaker on '{name}'.[/green]")
+        return
+
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    # `overflow="fold"` on the flow name: rich shrinks the widest column when
+    # the table outgrows the terminal, and the default is an ellipsis. The
+    # name is exactly what the operator has to retype into `flow retry`, so it
+    # wraps rather than being cut. `Reason` comes last for the same reason --
+    # it is the column the wrapping should land on.
+    table.add_column("Flow", overflow="fold")
+    table.add_column("State")
+    table.add_column("Opened")
+    table.add_column("Retry after")
+    table.add_column("Opens", justify="right")
+    table.add_column("Reason", overflow="fold")
+
+    for breaker in breakers:
+        opens = breaker.get("opens")
+        table.add_row(
+            str(breaker.get("name") or ""),
+            str(breaker.get("state") or ""),
+            _relative(breaker.get("opened_at")),
+            _relative(breaker.get("retry_after_at")),
+            "" if opens is None else str(opens),
+            _reason(breaker),
+        )
+
+    console.print(f"\n[bold]Open circuit breakers: {name}[/bold]\n")
+    console.print(table)
+    console.print(
+        f"\nRetry one now with: plugsync connector flow retry {name} <flow>",
+        soft_wrap=True,
+    )
+    console.print(
+        "A flow whose retry window has already passed is probed automatically "
+        "by the next message it receives.\n",
+        soft_wrap=True,
+    )

{plugsync_cli-0.4.0 → plugsync_cli-0.6.0}/plugsync_cli/commands/diff.py

@@ -51,15 +51,20 @@ 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.
+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 +203,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 +234,42 @@ 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 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.
+    """
+    if key not in OPTIONAL_COLLECTIONS:
+        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",
+            key,
+            f"declared in the published version, absent from your files: "
+            f"pushing this directory takes the {key} out of the config",
+        )
+    ]
+
+
 def _simple(change_type: str, scope: str, detail: str) -> dict:
     return {
         "type": change_type,
@@ -264,7 +306,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-0.4.0 → plugsync_cli-0.6.0}/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-0.4.0 → plugsync_cli-0.6.0}/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-0.4.0 → plugsync_cli-0.6.0}/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:

{plugsync_cli-0.4.0 → plugsync_cli-0.6.0}/plugsync_cli/context.py

@@ -9,15 +9,17 @@ 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,
     write_config_directory,
@@ -128,10 +130,21 @@ 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.
     """
-    expected_version = None if force else _expected_draft_version(client, context)
+    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)
+    )
     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 +152,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))
 
     warn_if_flow_order_is_not_preserved(draft["config"])
     write_config_directory(context.directory, draft["config"])
@@ -155,17 +170,84 @@ def write_draft_from_directory(
     return draft
 
 
-def _expected_draft_version(client: PlugSyncClient, context: ConnectorContext) -> int:
+def _rejection_pointing_at_the_files(exc: httpx.HTTPStatusError) -> 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.
+    """
+    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. 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.
+    """
+    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 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:
     """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 = client.get_draft(context.connector_id)["draft_version"]
+    current = (draft or 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.4.0 → plugsync_cli-0.6.0}/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: