agctl 0.1.0__py3-none-any.whl

agctl/__init__.py

@@ -0,0 +1 @@
+"""agctl — agent-facing CLI harness for testing distributed systems."""

agctl/assertion_registry.py

@@ -0,0 +1,243 @@
+"""Pluggable assertion-mode registry (DESIGN §9.3).
+
+New assertion modes for ``db assert`` / ``kafka assert`` are added by
+subclassing :class:`Assertion` and registering an instance (or the class) with
+an :class:`AssertionRegistry` keyed by its ``.name``. Third-party modes are
+discovered via the ``agctl.assertions`` entry-point group.
+
+This module is PRAGMATIC: it provides the extension point + discovery. The
+built-in ``db assert`` / ``kafka assert`` command logic continues to live in
+the command modules (``db_commands.py`` / ``kafka_commands.py``) — those modes
+are also registered here by NAME so that:
+
+(a) known built-in mode names are discoverable (``registry.names()``),
+(b) an unknown mode resolves to a clear :class:`TemplateNotFound` error, and
+(c) third-party entry points can extend the set of available modes.
+
+The registry guarantees ``registry.get(name)`` returns an :class:`Assertion`
+instance for any registered mode; calling ``evaluate`` on a built-in mode
+raises :class:`NotImplementedError` because the real logic is in the command
+layer.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from typing import Any, Iterable, Union
+
+from .errors import TemplateNotFound
+
+#: Entry-point group for third-party assertion modes (DESIGN §9.3).
+ASSERTION_ENTRY_POINT_GROUP = "agctl.assertions"
+
+
+def _entry_points(group: str) -> list:
+    """Return entry points registered under ``group`` (3.11+ shim).
+
+    Mirrors :func:`agctl.cli._entry_points`. Factored out so tests can
+    monkeypatch discovery. Returns ``[]`` on any failure.
+    """
+    try:
+        eps = importlib.metadata.entry_points()
+        if hasattr(eps, "select"):
+            return list(eps.select(group=group))
+        return list(eps.get(group, []))
+    except Exception:
+        return []
+
+
+class Assertion:
+    """Base class for pluggable assertion modes (DESIGN §9.3).
+
+    Subclasses set :attr:`name` (the mode key, e.g. ``'expect_rows'`` or a
+    third-party ``'json_schema'``) and implement :meth:`evaluate`.
+
+    ``evaluate`` receives a free-form ``context`` dict and returns a result
+    dict with at least ``{"passed": bool}`` plus any assertion-specific
+    fields. Either raise :class:`AssertionFailure` on failure (the command
+    layer translates that) or return ``{"passed": False, ...}`` and let the
+    command raise. Keep the contract simple: ``evaluate`` returns a dict;
+    ``passed=False`` means fail.
+    """
+
+    name: str = ""
+
+    def evaluate(self, context: dict) -> dict:  # pragma: no cover - interface
+        raise NotImplementedError
+
+
+class _BuiltInMode(Assertion):
+    """Marker subclass for built-in modes.
+
+    Built-in modes are implemented inline in the command layer; calling
+    ``evaluate`` on one raises so a caller can't accidentally bypass the
+    command's validated path. The registry registers these by NAME purely for
+    discovery and unknown-mode rejection.
+    """
+
+    def evaluate(self, context: dict) -> dict:
+        raise NotImplementedError(
+            f"built-in mode '{self.name}' is implemented in the command layer"
+        )
+
+
+# The built-in mode names registered in the default registry.
+_BUILT_IN_MODES: tuple[str, ...] = (
+    "expect_rows",
+    "expect_value",
+    "contains",
+    "match",
+    "pattern",
+)
+
+
+class AssertionRegistry:
+    """Registry of assertion modes keyed by :attr:`Assertion.name`."""
+
+    def __init__(self) -> None:
+        self._modes: dict[str, Assertion] = {}
+
+    def register(
+        self, assertion_cls_or_instance: Union[type, Assertion]
+    ) -> None:
+        """Register an :class:`Assertion` subclass or instance, keyed by ``.name``.
+
+        A class is instantiated once; an instance is used as-is. A blank
+        ``.name`` is ignored (no-op) so a misconfigured entry point can't
+        shadow real modes.
+        """
+        if isinstance(assertion_cls_or_instance, Assertion):
+            instance = assertion_cls_or_instance
+        elif isinstance(assertion_cls_or_instance, type) and issubclass(
+            assertion_cls_or_instance, Assertion
+        ):
+            instance = assertion_cls_or_instance()
+        else:
+            # Not an Assertion at all: ignore rather than corrupt the registry.
+            return
+        name = getattr(instance, "name", "") or ""
+        if not name:
+            return
+        self._modes[name] = instance
+
+    def get(self, name: str) -> Assertion:
+        """Resolve a mode by name.
+
+        Raises :class:`TemplateNotFound` (DESIGN §4.1) for unknown modes so the
+        command layer's existing error handling maps it to a clean envelope.
+        """
+        try:
+            return self._modes[name]
+        except KeyError:
+            raise TemplateNotFound(
+                f"Unknown assertion mode: {name}", {"mode": name}
+            )
+
+    def names(self) -> list[str]:
+        """Sorted list of registered mode names."""
+        return sorted(self._modes)
+
+    def load_entry_points(self) -> "AssertionRegistry":
+        """Load third-party modes from the ``agctl.assertions`` group.
+
+        Each load is wrapped in try/except so a single broken entry point is
+        skipped (logged to stderr) rather than bricking the registry. Returns
+        ``self`` for chaining.
+        """
+        import sys
+
+        for ep in _entry_points(ASSERTION_ENTRY_POINT_GROUP):
+            try:
+                obj = ep.load()
+            except Exception as exc:  # noqa: BLE001 - entry-point isolation
+                print(
+                    f"agctl: failed to load assertion mode {ep.name}: {exc}",
+                    file=sys.stderr,
+                )
+                continue
+            self.register(obj)
+        return self
+
+
+# --- module-level default registry -----------------------------------------
+
+
+def _default_registry() -> AssertionRegistry:
+    """Build a fresh registry with the built-in modes registered.
+
+    Does NOT load entry points — entry-point loading happens once in
+    :func:`get_default_registry` so the cached registry reflects the real
+    environment.
+    """
+    reg = AssertionRegistry()
+    for mode_name in _BUILT_IN_MODES:
+        # A distinct subclass per name keeps each registered instance's
+        # ``.name`` accurate for introspection.
+        cls = type(f"_BuiltIn_{mode_name}", (_BuiltInMode,), {"name": mode_name})
+        reg.register(cls)
+    return reg
+
+
+_DEFAULT_REGISTRY: AssertionRegistry | None = None
+
+
+def get_default_registry() -> AssertionRegistry:
+    """Return the cached default registry (built-ins + loaded entry points).
+
+    Built once on first call; subsequent calls return the same instance so
+    entry-point loading is not repeated.
+    """
+    global _DEFAULT_REGISTRY
+    if _DEFAULT_REGISTRY is None:
+        reg = _default_registry()
+        reg.load_entry_points()
+        _DEFAULT_REGISTRY = reg
+    return _DEFAULT_REGISTRY
+
+
+def evaluate_custom(name: str, context: dict, registry: "AssertionRegistry | None" = None):
+    """Resolve ``name`` and run its ``evaluate(context)`` (DESIGN §9.3).
+
+    This is the bridge that makes third-party ``agctl.assertions`` modes
+    reachable from ``db assert --assertion <name>`` / ``kafka assert --assertion
+    <name>``. ``context`` is a free-form dict the command builds for the mode
+    (rows/messages + metadata).
+
+    Returns ``(True, detail)`` on success. Raises:
+    - :class:`TemplateNotFound` (exit 2) for an unknown mode name.
+    - :class:`ConfigError` (exit 2) if ``name`` is a built-in mode (those have
+      dedicated flags and intentionally raise NotImplementedError from
+      ``evaluate``).
+    - :class:`AssertionFailure` (exit 1) if the mode returns ``passed=False``
+      or itself raises.
+
+    ``registry`` defaults to :func:`get_default_registry` (monkeypatchable).
+    """
+    from .errors import AssertionFailure, ConfigError
+
+    reg = registry if registry is not None else get_default_registry()
+    mode = reg.get(name)  # TemplateNotFound for unknown name
+    try:
+        result = mode.evaluate(context)
+    except AssertionFailure:
+        raise
+    except NotImplementedError:
+        raise ConfigError(
+            f"Built-in assertion mode '{name}' has dedicated flags; "
+            "do not invoke it via --assertion",
+            {"mode": name},
+        )
+    except Exception as exc:  # noqa: BLE001 - third-party mode isolation
+        raise AssertionFailure(f"assertion '{name}' raised: {exc}", {"mode": name})
+
+    if not isinstance(result, dict):
+        raise AssertionFailure(
+            f"assertion '{name}' returned a non-dict result", {"mode": name}
+        )
+    detail = {k: v for k, v in result.items() if k != "passed"}
+    if not result.get("passed"):
+        raise AssertionFailure(
+            result.get("message") or f"assertion '{name}' did not pass",
+            {"mode": name, **detail},
+        )
+    return True, detail

agctl/assertions.py

@@ -0,0 +1,135 @@
+"""Assertion primitives backing Kafka/DB checks.
+
+DESIGN §3.2 (jq predicate/value evaluation, silent skip on error),
+and D8 (equals coercion + type-aware comparison rules).
+"""
+
+import datetime
+import decimal
+import json
+import uuid
+
+from .errors import ConfigError
+
+
+def _jq():
+    """Lazily import jq so the package imports without the optional extra.
+    jq is only needed for match/path assertions (Kafka --match/--path, DB --path).
+    A missing library is a configuration problem -> ConfigError (exit 2), distinct
+    from a jq *expression* error (handled by callers as a silent skip per §3.2)."""
+    try:
+        import jq
+    except ImportError as exc:  # pragma: no cover - exercised via sys.modules in tests
+        raise ConfigError(
+            "jq is required for match/path assertions: pip install 'agctl[db]' or 'agctl[kafka]'",
+            {},
+        ) from exc
+    return jq
+
+
+def jq_bool(value, expr: str) -> bool:
+    """Evaluate a jq predicate against value; True only if the result is truthy.
+
+    A jq compile/runtime error OR a falsy/empty result -> False (silently skipped
+    per DESIGN §3.2). A missing jq library -> ConfigError (propagates, exit 2).
+    """
+    try:
+        outputs = _jq().compile(expr).input(value).all()
+    except ConfigError:
+        raise
+    except Exception:
+        return False
+    return any(bool(o) for o in outputs)
+
+
+def jq_value(value, expr: str):
+    """Evaluate a jq path/value expression (e.g. '.status'). Returns the first
+    output value, or None if the expression errors or yields nothing. A missing jq
+    library -> ConfigError (propagates, exit 2)."""
+    try:
+        outputs = _jq().compile(expr).input(value).all()
+    except ConfigError:
+        raise
+    except Exception:
+        return None
+    if not outputs:
+        return None
+    return outputs[0]
+
+
+def json_subset(needle, haystack) -> bool:
+    """DESIGN --contains: True if every key/element in needle is present-and-equal
+    in haystack, recursively for nested dict/list. Subset, not equality.
+
+    - dict needle: every key in needle must exist in haystack with a
+      json_subset-equal value.
+    - list needle: every element of needle must be json_subset-matched by SOME
+      element of haystack (order-independent).
+    - scalar needle: needle == haystack.
+    """
+    if isinstance(needle, dict):
+        if not isinstance(haystack, dict):
+            return False
+        return all(
+            k in haystack and json_subset(v, haystack[k]) for k, v in needle.items()
+        )
+    if isinstance(needle, list):
+        if not isinstance(haystack, list):
+            return False
+        # each needle element must match at least one haystack element
+        return all(
+            any(json_subset(n, h) for h in haystack) for n in needle
+        )
+    # scalar
+    return needle == haystack
+
+
+def parse_equals(text: str):
+    """DESIGN D8 step 1-2: try json.loads(text); if it parses, return the typed
+    value ('0'->int 0, 'true'->bool True, 'null'->None, '[1,2]'->[1,2]); else
+    return the raw string."""
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return text
+
+
+def coerce_db_value(value):
+    """DESIGN D8 step 3: coerce a DB cell to a JSON-native type before comparison.
+
+    - None -> None
+    - bool -> bool (checked BEFORE int; bool is a subclass of int in Python)
+    - decimal.Decimal -> int if integral else float
+    - datetime.datetime/datetime.date/datetime.time -> .isoformat()
+    - uuid.UUID -> str(value)
+    - int/float/str -> unchanged
+    - everything else -> unchanged
+    """
+    if value is None:
+        return None
+    # bool MUST be checked before int (bool subclasses int)
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, decimal.Decimal):
+        if value % 1 == 0:
+            return int(value)
+        return float(value)
+    if isinstance(value, (datetime.datetime, datetime.date, datetime.time)):
+        return value.isoformat()
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    return value
+
+
+def type_aware_equal(expected, actual) -> bool:
+    """DESIGN D8 step 4: strict, type-aware equality. 0 != '0' (number vs string).
+
+    A number never equals a string of the same digits. Otherwise compares with ==,
+    recursing element-wise for dict/list.
+    """
+    # number-vs-string mismatch (in either order) -> never equal
+    if isinstance(expected, (int, float, decimal.Decimal, bool)) and isinstance(actual, str):
+        return False
+    if isinstance(actual, (int, float, decimal.Decimal, bool)) and isinstance(expected, str):
+        return False
+    return expected == actual

agctl/cli.py

@@ -0,0 +1,163 @@
+"""Click entry point (DESIGN §3, §7). Wires command groups and emits envelopes.
+
+The ``config`` command group lives in :mod:`agctl.commands.config_commands`;
+plugin loading (``_load_plugins`` / ``_LOADED_PLUGINS``) stays here because it
+is a CLI-bootstrap concern. Config validation reads the live plugin list via a
+thunk injected into ``config_commands`` (see :func:`set_plugins_provider`), so
+the dependency runs one way: ``cli → config_commands``.
+"""
+
+import importlib.metadata
+import sys
+from typing import Any
+
+import click
+
+from .commands.check_commands import check_ready
+from .commands.config_commands import (
+    config_show,
+    config_validate,
+    set_plugins_provider,
+)
+from .commands.db_commands import db_assert, db_query
+from .commands.discover_commands import discover
+from .commands.http_commands import http_call, http_ping, http_request
+from .commands.kafka_commands import kafka_assert, kafka_consume, kafka_produce
+
+#: Entry-point group for third-party protocol plugins (DESIGN §9.2).
+PLUGIN_ENTRY_POINT_GROUP = "agctl.plugins"
+
+#: Plugins successfully loaded at import time (DESIGN §9.2). Populated by
+#: :func:`_load_plugins`; read by ``agctl config validate`` via the thunk passed
+#: to :func:`agctl.commands.config_commands.set_plugins_provider` so each plugin
+#: can validate its own config section.
+_LOADED_PLUGINS: list[Any] = []
+
+
+def _entry_points(group: str) -> list:
+    """Return the entry points registered under ``group`` (3.11+ shim).
+
+    Factored out so tests can monkeypatch discovery. Returns ``[]`` on any
+    failure (a broken importlib state must never crash the CLI).
+    """
+    try:
+        eps = importlib.metadata.entry_points()
+        if hasattr(eps, "select"):
+            return list(eps.select(group=group))
+        return list(eps.get(group, []))
+    except Exception:
+        return []
+
+
+def _load_plugins(cli_group: click.Group) -> None:
+    """Load ``agctl.plugins`` entry points onto ``cli_group`` (DESIGN §9.2).
+
+    Each plugin object exposes ``.command_group`` (a :class:`click.Group`) and
+    optionally ``.name`` (subcommand name) and ``.validate_config(config)``
+    (consulted by ``agctl config validate`` via the provider set below). Each
+    load+register is wrapped in try/except so a broken plugin logs to stderr
+    and is skipped rather than bricking the CLI. An empty/missing
+    ``agctl.plugins`` group is a clean no-op. Successfully loaded plugins are
+    recorded in ``_LOADED_PLUGINS`` so config validation can delegate to them.
+    """
+    global _LOADED_PLUGINS
+    _LOADED_PLUGINS = []
+    try:
+        for ep in _entry_points(PLUGIN_ENTRY_POINT_GROUP):
+            try:
+                obj = ep.load()
+            except Exception as exc:  # noqa: BLE001 - plugin isolation
+                print(f"agctl: failed to load plugin {ep.name}: {exc}", file=sys.stderr)
+                continue
+            command_group = getattr(obj, "command_group", None)
+            if isinstance(command_group, click.Group):
+                # DESIGN §9.2: `.name` is the subcommand name; fall back to the
+                # group's own name, then the entry-point name.
+                name = getattr(obj, "name", None) or command_group.name or ep.name
+                cli_group.add_command(command_group, name=name)
+                _LOADED_PLUGINS.append(obj)
+            else:
+                print(
+                    f"agctl: plugin {ep.name} has no valid command_group; skipping",
+                    file=sys.stderr,
+                )
+    except Exception as exc:  # noqa: BLE001 - never let the loader crash the CLI
+        print(f"agctl: plugin loader error: {exc}", file=sys.stderr)
+
+
+@click.group()
+@click.option("--config", "config_path", default=None, help="Path to agctl.yaml")
+@click.pass_context
+def cli(ctx: click.Context, config_path: str | None) -> None:
+    """agctl — agent-facing CLI harness for testing distributed systems."""
+    ctx.ensure_object(dict)
+    ctx.obj["config_path"] = config_path
+
+
+@cli.group(name="config")
+def config_group() -> None:
+    """Config introspection."""
+
+
+@cli.group(name="http")
+def http_group() -> None:
+    """HTTP request commands."""
+
+
+@cli.group(name="db")
+def db_group() -> None:
+    """Database query/assert commands."""
+
+
+@cli.group(name="kafka")
+def kafka_group() -> None:
+    """Kafka produce/consume/assert commands."""
+
+
+@cli.group(name="check")
+def check_group() -> None:
+    """Health/readiness checks."""
+
+
+# Register subcommands on the config group (commands live in config_commands.py).
+config_group.add_command(config_validate)
+config_group.add_command(config_show)
+
+# Register subcommands on the http group.
+http_group.add_command(http_call)
+http_group.add_command(http_request)
+http_group.add_command(http_ping)
+
+
+# Register subcommands on the db group.
+db_group.add_command(db_query)
+db_group.add_command(db_assert)
+
+
+# Register subcommands on the kafka group.
+kafka_group.add_command(kafka_produce)
+kafka_group.add_command(kafka_consume)
+kafka_group.add_command(kafka_assert)
+
+
+# Register subcommands on the check group.
+check_group.add_command(check_ready)
+
+
+# Register the top-level `discover` command directly on the root group.
+cli.add_command(discover)
+
+
+# Bridge config validation to the live loaded-plugins list. The thunk reads this
+# module's ``_LOADED_PLUGINS`` global at call time, so it stays correct even after
+# :func:`_load_plugins` reassigns that global.
+set_plugins_provider(lambda: _LOADED_PLUGINS)
+
+
+# Load third-party protocol plugins (DESIGN §9.2). A clean no-op today since no
+# plugins are registered; guarded so a broken plugin/importlib never bricks the CLI.
+_load_plugins(cli)
+
+
+if __name__ == "__main__":
+    cli()

agctl/clients/db_client.py

@@ -0,0 +1,94 @@
+"""DbClient with entry-point driver dispatch (DESIGN §9.1).
+
+Selects a :class:`DBDriver` implementation by the connection's ``type`` field,
+discovering third-party drivers via the ``agctl.db_drivers`` entry-point group
+while always falling back to the built-in ``postgresql`` driver.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from typing import Any
+
+from ..errors import ConfigError
+from .db_drivers.postgresql import PostgreSQLDriver
+
+#: Entry-point group used to discover third-party DB drivers.
+DB_DRIVER_ENTRY_POINT_GROUP = "agctl.db_drivers"
+
+#: Built-in drivers always available even without entry-point registration.
+BUILTIN_DRIVERS: dict[str, type] = {"postgresql": PostgreSQLDriver}
+
+
+class DbClient:
+    """High-level database client that delegates to a discovered driver.
+
+    The driver is selected by ``connection["type"]``:
+
+    - If ``driver`` is injected (DI), it is used directly and no lookup occurs.
+    - Otherwise the driver class is looked up in ``drivers`` (or
+      :meth:`load_drivers` by default) and instantiated.
+    """
+
+    def __init__(
+        self,
+        connection: Any,
+        *,
+        driver: Any = None,
+        drivers: dict[str, type] | None = None,
+    ) -> None:
+        # Normalize the connection into a plain dict (pydantic models expose
+        # model_dump(); plain dicts pass through unchanged).
+        self._conn_dict = getattr(connection, "model_dump", lambda: connection)()
+
+        if driver is not None:
+            self._driver = driver
+        else:
+            available = drivers if drivers is not None else self.load_drivers()
+            db_type = self._conn_dict.get("type")
+            if not db_type or db_type not in available:
+                raise ConfigError(
+                    f"Unknown database type: {db_type}", {"type": db_type}
+                )
+            driver_class = available[db_type]
+            self._driver = driver_class()
+
+    @classmethod
+    def load_drivers(cls) -> dict[str, type]:
+        """Discover DB drivers via entry points, merging built-ins.
+
+        Returns a ``{type_name: driver_class}`` mapping. The built-in
+        ``postgresql`` driver is always present. Broken third-party drivers
+        (``.load()`` raising) are skipped rather than crashing discovery.
+        """
+        drivers: dict[str, type] = {}
+        try:
+            eps = importlib.metadata.entry_points()
+            group = (
+                eps.select(group=DB_DRIVER_ENTRY_POINT_GROUP)
+                if hasattr(eps, "select")
+                else eps.get(DB_DRIVER_ENTRY_POINT_GROUP, [])
+            )
+        except Exception:  # pragma: no cover - defensive; shouldn't happen
+            group = []
+
+        for ep in group:
+            try:
+                driver_class = ep.load()
+            except Exception:
+                # A broken third-party driver must not break discovery.
+                continue
+            drivers[ep.name] = driver_class
+
+        # Built-ins are always available and win over any registration gaps.
+        drivers.update(BUILTIN_DRIVERS)
+        return drivers
+
+    def connect(self) -> None:
+        self._driver.connect(self._conn_dict)
+
+    def execute(self, sql: str, params: dict) -> list[dict]:
+        return self._driver.execute(sql, params)
+
+    def close(self) -> None:
+        self._driver.close()

agctl/clients/db_driver_protocol.py

@@ -0,0 +1,27 @@
+"""DBDriver protocol (DESIGN §9.1).
+
+A minimal structural protocol describing the contract every database driver
+must satisfy. Drivers are registered as entry points (``agctl.db_drivers``)
+and selected by the ``DbClient`` based on the connection's ``type`` config field.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DBDriver(Protocol):
+    """Structural contract for a database driver.
+
+    - :meth:`connect` opens (or retains an injected) connection from config.
+    - :meth:`execute` runs a read-only SQL statement with named params and
+      returns a list of dict rows (column name -> coerced value).
+    - :meth:`close` releases the connection if the driver owns it.
+    """
+
+    def connect(self, config: dict) -> None: ...
+
+    def execute(self, sql: str, params: dict) -> list[dict[str, Any]]: ...
+
+    def close(self) -> None: ...