agent-tool-shared-cli 0.1.0__py3-none-any.whl

agent_tool_shared_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: agent-tool-shared-cli
+Version: 0.1.0
+Summary: Shared chassis for agent-ready CLIs: the exit-code contract, JSON/table/markdown/CSV output with field projection, and keyring-backed credentials.
+Author: Zierhut IT, Alexander Zierhut
+License: MIT
+Project-URL: Homepage, https://github.com/alexander-zierhut/agent-tool-shared-cli
+Project-URL: Repository, https://github.com/alexander-zierhut/agent-tool-shared-cli
+Project-URL: Issues, https://github.com/alexander-zierhut/agent-tool-shared-cli/issues
+Keywords: cli,command-line,ai-agent,llm,automation,json-output,keyring,exit-codes,agent-ready
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: keyring>=25
+Requires-Dist: rich>=13
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-timeout>=2.3; extra == "test"
+
+# agent-tool-shared-cli
+
+The shared chassis for the **`agent-tool-<x>-cli`** family — agent-ready command-line
+tools that an LLM can drive with no prior knowledge of them.
+
+Consumers: [`agent-tool-openproject-cli`](https://github.com/alexander-zierhut/agent-tool-openproject-cli),
+`agent-tool-drone-cli` (in progress).
+
+This repo also holds **[BLUEPRINT.md](BLUEPRINT.md)** — the engineering standard the
+whole family is built to. Read that first if you are standing up a new tool.
+
+```bash
+pip install agent-tool-shared-cli
+```
+
+## What's in it
+
+This package is deliberately small. It holds **the agent contract** and the pure
+utilities that implement it — the things that must be *identical* across every tool,
+because an agent learns the contract once and applies it everywhere.
+
+| Module | What |
+|---|---|
+| `agentcli.errors` | The exit-code taxonomy (`0/1/3/4/5/6/7/130`) + `DryRun` |
+| `agentcli.output` | `Emitter`: json/table/markdown/csv, `--fields` projection, NDJSON streaming |
+| `agentcli.credentials` | Keyring storage with a `0600` fallback and an env override |
+| `agentcli.appspec` | `AppSpec` — the two strings that make all of the above tool-specific |
+
+```python
+from agentcli import AppSpec, Credentials, Emitter, OutputFormat, NotFoundError
+
+SPEC = AppSpec(name="drone-cli", env_prefix="DRONECLI")
+
+SPEC.config_dir()            # ~/.config/drone-cli  (or $DRONECLI_CONFIG_DIR)
+SPEC.env("TOKEN")            # "DRONECLI_TOKEN"
+
+Credentials(SPEC).get_token("default")     # env > keyring > 0600 file
+Emitter(OutputFormat.json, fields=["id", "status"]).emit(rows)
+raise NotFoundError("no such build")       # -> exit 5, JSON on stderr
+```
+
+## The exit-code contract
+
+Published API. You may leave a code unallocated, or repurpose one deliberately.
+**You may never renumber one** — agents branch on these, and they are documented in
+three places per tool (README, the in-binary `guide`, and the Claude skill).
+
+| Code | Meaning |
+|---|---|
+| 0 | success (including a successful `--dry-run`) |
+| 1 | generic error |
+| 2 | *reserved for Click/Typer usage errors — never allocate* |
+| 3 | config error |
+| 4 | auth error (401/403) |
+| 5 | not found (404) |
+| 6 | conflict (409 / optimistic locking) |
+| 7 | validation error (422) — see `fieldErrors` |
+| 8+ | per-tool, and only for a condition you have **observed** |
+| 130 | SIGINT |
+
+## What is deliberately NOT here
+
+`client.py`, `serialize.py`, `resolve.py` and the domain commands stay in each tool.
+They *look* shareable and are not:
+
+> OpenProject stops paginating on an authoritative `total` — "never stop on a short
+> page". Drone has no total, and a short page **is** the terminator. The rule that
+> inverts between tool #1 and tool #2 is exactly the rule you must not hoist.
+
+Auth schemes, retry matrices and error-body shapes are the same story. Pulling them in
+would make this a framework with a config object per tool, which is how shared-code
+projects die.
+
+**Share the contract, not the transport.**
+
+## Contributing
+
+You need nothing but Python:
+
+```bash
+pip install -e '.[test]'
+pytest                       # 74 tests, no network, no services
+```
+
+Changes here affect every downstream CLI. Two rules:
+
+1. **Never renumber an exit code, and never change an output shape** without treating
+   it as a breaking change — downstream agents depend on both.
+2. **Don't add a module because two tools happen to share it today.** Wait until a
+   third does, and until you can state the rule it obeys. `tests/test_contract.py`
+   is the tripwire: if a change makes you edit it, stop and think.
+
+## License
+
+MIT

agent_tool_shared_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agentcli/__init__.py,sha256=tMQp6u5MjpCDHfQghecUYavmAYc2TOvwU3Z1l6Tzdp4,1959
+agentcli/appspec.py,sha256=LatDORrPGDRa3MgV8hlTLw3eULqwjFkqp2s4l81dBZU,3883
+agentcli/credentials.py,sha256=FOrnn4xtfXRT9rGHwfaJjAW0adayNNajZvz7pp8rmok,5229
+agentcli/errors.py,sha256=AUDkETdEsa9DB6KnY8-pVASLv_31G2ENtspDquR21gg,2467
+agentcli/output.py,sha256=jhPlzOdeioV5cHvfZ-JaJJP007MXwRxASmTkZScDRO4,10576
+agent_tool_shared_cli-0.1.0.dist-info/METADATA,sha256=E6-gzK9e_eHjT8TFLq1_Y4sJrmMnqHQ0EV_2NbNQPYk,4759
+agent_tool_shared_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agent_tool_shared_cli-0.1.0.dist-info/top_level.txt,sha256=z-NsMAZGHtIei-p-W9E2SURJ0eDY6L-t0epXY-eIkc8,9
+agent_tool_shared_cli-0.1.0.dist-info/RECORD,,

agent_tool_shared_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_tool_shared_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentcli

agentcli/__init__.py

@@ -0,0 +1,58 @@
+"""agentcli — the shared chassis for `agent-tool-<x>-cli` tools.
+
+This package is deliberately small. It holds **the agent contract** and the pure
+utilities that implement it — the things that must be *identical* across every
+tool we ship, because an agent learns the contract once and applies it everywhere:
+
+* :mod:`agentcli.errors`      — the exit-code taxonomy (0/1/3/4/5/6/7/130) + ``DryRun``
+* :mod:`agentcli.output`      — json/table/markdown/csv, ``--fields`` projection, NDJSON
+* :mod:`agentcli.credentials` — keyring with a 0600 fallback and an env override
+* :mod:`agentcli.appspec`     — the two strings that make the above tool-specific
+
+**What is deliberately NOT here**, and why it matters more than what is:
+
+``client.py``, ``serialize.py``, ``resolve.py`` and the domain command modules
+stay in each tool. They *look* shareable and are not — OpenProject's pagination
+stops on an authoritative ``total`` ("never stop on a short page"), while Drone
+has no total and a short page IS the terminator. The rule that inverts between
+tool #1 and tool #2 is exactly the rule you must not hoist. Auth schemes, retry
+matrices and error-body shapes are the same story.
+
+    Share the contract, not the transport.
+
+Pulling those in would turn this into a framework with a config object per tool,
+which is how shared-code projects die.
+"""
+
+from .appspec import AppSpec
+from .credentials import Credentials
+from .errors import (
+    ApiError,
+    AuthError,
+    ConfigError,
+    ConflictError,
+    DryRun,
+    NotFoundError,
+    OpError,
+    ValidationError,
+)
+from .output import Emitter, OutputFormat, print_error  # NDJSON is Emitter.stream_json()
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AppSpec",
+    "Credentials",
+    "Emitter",
+    "OutputFormat",
+    "print_error",
+    "OpError",
+    "ApiError",
+    "AuthError",
+    "ConfigError",
+    "ConflictError",
+    "NotFoundError",
+    "ValidationError",
+    "DryRun",
+    "__version__",
+]

agentcli/appspec.py

@@ -0,0 +1,96 @@
+"""`AppSpec` — the two strings that make a shared chassis tool-specific.
+
+Every tool in the `agent-tool-<x>-cli` family needs the same four things from
+its identity:
+
+* a **config directory**       ``~/.config/<name>/``
+* a **keyring service name**   ``<name>``
+* an **env-var namespace**     ``<PREFIX>_TOKEN``, ``<PREFIX>_CONFIG_DIR``, …
+* a **relocatable config dir**, so tests are hermetic
+
+So that is all `AppSpec` carries. It is deliberately not a plugin system, a
+registry or a settings framework — two strings and a few pure functions.
+
+Why this exists at all: in `opcli` the config-dir logic was **duplicated** in
+both ``config.py`` and ``credentials.py``. Two copies of "where do I live?" that
+nothing forced to agree — relocate one and the token and the profile end up in
+different directories. Here there is exactly one.
+
+    SPEC = AppSpec(name="op-cli", env_prefix="OPCLI")
+    SPEC.config_dir()          # -> ~/.config/op-cli   (or $OPCLI_CONFIG_DIR)
+    SPEC.env("TOKEN")          # -> "OPCLI_TOKEN"
+    SPEC.getenv("BASE_URL")    # -> os.environ.get("OPCLI_BASE_URL")
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AppSpec:
+    """Identity of one CLI. Frozen: this is configuration, not state."""
+
+    name: str
+    """Directory + keyring service name, e.g. ``op-cli``, ``drone-cli``."""
+
+    env_prefix: str
+    """Env-var namespace WITHOUT the trailing underscore, e.g. ``OPCLI``."""
+
+    def __post_init__(self) -> None:
+        # These two are the whole contract; a typo here silently relocates a
+        # user's config or splits their token from their profile.
+        if not self.name or "/" in self.name:
+            raise ValueError(f"AppSpec.name must be a bare directory name, got {self.name!r}")
+        if not self.env_prefix or not self.env_prefix.isupper():
+            raise ValueError(
+                f"AppSpec.env_prefix must be UPPERCASE and non-empty, got {self.env_prefix!r}"
+            )
+        if self.env_prefix.endswith("_"):
+            raise ValueError(
+                f"AppSpec.env_prefix must not end with '_' (it is added for you), got {self.env_prefix!r}"
+            )
+
+    # ---- env ---------------------------------------------------------
+
+    def env(self, suffix: str) -> str:
+        """The full env-var name for *suffix*: ``env("TOKEN") -> "OPCLI_TOKEN"``."""
+        return f"{self.env_prefix}_{suffix}"
+
+    def getenv(self, suffix: str, default: str | None = None) -> str | None:
+        """Read ``<PREFIX>_<SUFFIX>`` from the environment."""
+        return os.environ.get(self.env(suffix), default)
+
+    # ---- paths -------------------------------------------------------
+
+    def config_dir(self) -> Path:
+        """Where this tool's config lives.
+
+        A **function, not a module constant** — and that single property is what
+        makes the test suites hermetic. As a constant it would freeze at import
+        time, before a test could point ``<PREFIX>_CONFIG_DIR`` at a tmpdir, and
+        every test run would read and write the developer's real config.
+
+        Precedence: ``<PREFIX>_CONFIG_DIR`` > ``XDG_CONFIG_HOME``/<name> > ``~/.config/<name>``.
+        """
+        base = self.getenv("CONFIG_DIR")
+        if base:
+            return Path(base)
+        xdg = os.environ.get("XDG_CONFIG_HOME")
+        root = Path(xdg) if xdg else Path.home() / ".config"
+        return root / self.name
+
+    def config_file(self) -> Path:
+        return self.config_dir() / "config.json"
+
+    def credentials_file(self) -> Path:
+        """The 0600 fallback used only when no OS keyring is available."""
+        return self.config_dir() / "credentials.json"
+
+    # ---- keyring -----------------------------------------------------
+
+    @property
+    def keyring_service(self) -> str:
+        return self.name

agentcli/credentials.py

@@ -0,0 +1,145 @@
+"""Secure storage of API tokens, shared by every agent-tool CLI.
+
+Order of preference for reading a token:
+
+1. The ``<PREFIX>_TOKEN`` environment variable (used by CI / test suites and
+   handy for one-off scripting). **This is what makes a tool non-interactive** —
+   with it set, nothing touches the keyring and nothing can prompt.
+2. The operating-system keyring (Secret Service / macOS Keychain / Windows
+   Credential Locker) via the :mod:`keyring` library — the safe default.
+3. A ``0600`` fallback file in the config directory, used only when no real
+   keyring backend is available (headless boxes without a Secret Service).
+   We warn loudly in that case because the token is stored in clear text.
+
+The token is the only secret we persist. Everything else (base URL, options)
+lives in the plain-text config file.
+
+Parameterized by :class:`~agentcli.appspec.AppSpec` — the keyring service, the
+env var and the fallback path all derive from it, so two tools installed side by
+side never read each other's tokens.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+from .appspec import AppSpec
+
+
+def _keyring_available() -> bool:
+    try:
+        import keyring
+        from keyring.backends import fail
+
+        # keyring always "works" — it just installs a null backend that raises on
+        # use. Only an isinstance check tells you whether it will actually store.
+        return not isinstance(keyring.get_keyring(), fail.Keyring)
+    except Exception:
+        return False
+
+
+class Credentials:
+    """Token storage for one tool, identified by its :class:`AppSpec`."""
+
+    def __init__(self, spec: AppSpec) -> None:
+        self.spec = spec
+
+    # ---- internals ---------------------------------------------------
+
+    @property
+    def env_token(self) -> str:
+        return self.spec.env("TOKEN")
+
+    def _fallback_file(self) -> Path:
+        return self.spec.credentials_file()
+
+    def _read_fallback(self) -> dict[str, str]:
+        path = self._fallback_file()
+        if not path.exists():
+            return {}
+        try:
+            return json.loads(path.read_text())
+        except Exception:
+            return {}
+
+    def _write_fallback(self, data: dict[str, str]) -> None:
+        path = self._fallback_file()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # Create with 0600 from the start so the plaintext token is never briefly
+        # world-readable (mode 0o600 has no group/other bits, so umask can't widen it).
+        fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as fh:
+            json.dump(data, fh, indent=2)
+        try:
+            path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # also fixes a pre-existing file
+        except OSError:
+            pass
+
+    # ---- api ---------------------------------------------------------
+
+    def backend_name(self) -> str:
+        """Human-readable name of the active secret backend (for `auth status`)."""
+        if os.environ.get(self.env_token):
+            return f"environment variable ${self.env_token}"
+        if _keyring_available():
+            try:
+                import keyring
+
+                return f"OS keyring ({keyring.get_keyring().__class__.__name__})"
+            except Exception:
+                pass
+        return f"plaintext fallback file ({self._fallback_file()})"
+
+    def store_token(self, profile: str, token: str) -> str:
+        """Persist *token* for *profile*. Returns the backend used."""
+        if _keyring_available():
+            try:
+                import keyring
+
+                keyring.set_password(self.spec.keyring_service, profile, token)
+                return "keyring"
+            except Exception as exc:  # pragma: no cover - depends on host
+                print(f"warning: keyring store failed ({exc}); using fallback file", file=sys.stderr)
+        data = self._read_fallback()
+        data[profile] = token
+        self._write_fallback(data)
+        print(
+            f"warning: no OS keyring available — token stored in clear text at "
+            f"{self._fallback_file()} (0600)",
+            file=sys.stderr,
+        )
+        return "file"
+
+    def get_token(self, profile: str) -> str | None:
+        """Resolve the token for *profile*, honouring the env override first."""
+        env = os.environ.get(self.env_token)
+        if env:
+            return env
+        if _keyring_available():
+            try:
+                import keyring
+
+                tok = keyring.get_password(self.spec.keyring_service, profile)
+                if tok:
+                    return tok
+            except Exception:
+                pass
+        return self._read_fallback().get(profile)
+
+    def delete_token(self, profile: str) -> None:
+        """Remove any stored token for *profile* from every backend."""
+        if _keyring_available():
+            try:
+                import keyring
+
+                keyring.delete_password(self.spec.keyring_service, profile)
+            except Exception:
+                pass
+        data = self._read_fallback()
+        if profile in data:
+            del data[profile]
+            self._write_fallback(data)

agentcli/errors.py

@@ -0,0 +1,93 @@
+"""Exception types for the the API CLI.
+
+Every user-facing failure funnels through :class:`OpError` so the CLI entry
+point can render a single, clean error line (and a JSON error object when
+``-o json`` is active) instead of a Python traceback.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class OpError(Exception):
+    """Base class for all expected, user-facing errors."""
+
+    exit_code = 1
+
+    def __init__(self, message: str, *, detail: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"error": self.message}
+        if self.detail is not None:
+            out["detail"] = self.detail
+        return out
+
+
+class DryRun(Exception):
+    """Raised by the client in --dry-run mode instead of performing a write.
+
+    Carries the request that *would* have been sent so the CLI can print it and
+    exit 0 without touching the server.
+    """
+
+    def __init__(self, request: dict):
+        super().__init__("dry run")
+        self.request = request
+
+
+class ConfigError(OpError):
+    """Something is wrong with configuration or stored credentials."""
+
+    exit_code = 3
+
+
+class AuthError(OpError):
+    """Authentication/authorization failed (401/403)."""
+
+    exit_code = 4
+
+
+class NotFoundError(OpError):
+    """A requested resource does not exist (404)."""
+
+    exit_code = 5
+
+
+class ConflictError(OpError):
+    """Optimistic-locking or uniqueness conflict (409/422 stale lockVersion)."""
+
+    exit_code = 6
+
+
+class ValidationError(OpError):
+    """The server rejected the request payload (422)."""
+
+    exit_code = 7
+
+    def __init__(self, message: str, *, detail: Any = None, field_errors: Any = None):
+        super().__init__(message, detail=detail)
+        self.field_errors = field_errors
+
+    def to_dict(self) -> dict[str, Any]:
+        out = super().to_dict()
+        if self.field_errors:
+            out["fieldErrors"] = self.field_errors
+        return out
+
+
+class ApiError(OpError):
+    """A non-specific API error carrying the HTTP status and server payload."""
+
+    def __init__(self, message: str, *, status: int | None = None, detail: Any = None):
+        super().__init__(message, detail=detail)
+        self.status = status
+
+    def to_dict(self) -> dict[str, Any]:
+        out = super().to_dict()
+        if self.status is not None:
+            out["status"] = self.status
+        return out

agentcli/output.py

@@ -0,0 +1,288 @@
+"""Rendering of command results.
+
+The CLI is *agent-first*, so JSON is the default output: stable, complete, and
+trivial to parse. A ``table`` mode (Rich) exists for humans. Commands hand the
+formatter the raw data plus an optional column spec; the formatter decides how
+to present it based on the active ``--output`` mode.
+"""
+
+from __future__ import annotations
+
+import csv as csvlib
+import dataclasses
+import enum
+import json as jsonlib
+import sys
+from typing import Any, Callable, Iterable, Sequence
+
+from rich.console import Console
+from rich.table import Table
+
+# A column is (header, accessor). accessor is a dict key or a callable(row)->value.
+Column = tuple[str, "str | Callable[[dict], Any]"]
+
+_err_console = Console(stderr=True)
+
+
+class OutputFormat(str, enum.Enum):
+    json = "json"
+    table = "table"
+    markdown = "markdown"
+    csv = "csv"
+
+    @classmethod
+    def coerce(cls, value: "str | OutputFormat | None") -> "OutputFormat | None":
+        """Parse a loose string (accepts 'md' for markdown). None passes through."""
+        if value is None or isinstance(value, cls):
+            return value
+        v = str(value).strip().lower()
+        if v in ("md", "markdown"):
+            return cls.markdown
+        if v in ("json", "j"):
+            return cls.json
+        if v in ("table", "tbl", "t"):
+            return cls.table
+        if v in ("csv",):
+            return cls.csv
+        raise ValueError(f"unknown output format '{value}' (choose json, table, markdown, or csv)")
+
+
+def _accessor_value(row: dict, accessor: "str | Callable[[dict], Any]") -> Any:
+    if callable(accessor):
+        try:
+            return accessor(row)
+        except Exception:
+            return None
+    return row.get(accessor)
+
+
+def _fmt_cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, (list, tuple)):
+        return ", ".join(str(v) for v in value)
+    return str(value)
+
+
+class Emitter:
+    def __init__(
+        self,
+        fmt: OutputFormat = OutputFormat.json,
+        *,
+        color: bool = True,
+        fields: Sequence[str] | None = None,
+        stream: bool = False,
+    ):
+        self.fmt = fmt
+        self.console = Console(no_color=not color, highlight=False)
+        # user-selected fields (dotted paths ok, e.g. "assignee.name"); None = command defaults
+        self.fields = [f.strip() for f in fields if f.strip()] if fields else None
+        self.stream = stream
+
+    # ---- main entry --------------------------------------------------
+    def emit(
+        self,
+        data: Any,
+        *,
+        columns: Sequence[Column] | None = None,
+        title: str | None = None,
+        empty: str = "(no results)",
+    ) -> None:
+        if self.fields:
+            # --fields overrides both the JSON shape and the table/markdown columns
+            if self.fmt == OutputFormat.json:
+                self._emit_json(_project(data, self.fields))
+                return
+            columns = [(f, (lambda r, _f=f: _dotted_get(r, _f))) for f in self.fields]
+
+        if self.fmt == OutputFormat.json:
+            self._emit_json(data)
+            return
+        if self.fmt == OutputFormat.csv:
+            self._emit_csv(data, columns=columns)
+            return
+        if self.fmt == OutputFormat.markdown:
+            self._emit_markdown(data, columns=columns, title=title, empty=empty)
+            return
+        self._emit_table(data, columns=columns, title=title, empty=empty)
+
+    def stream_json(self, items: Iterable[Any]) -> int:
+        """Emit an iterable as NDJSON — one JSON object per line, flushed as it
+        arrives. Honours --fields. Returns the number of items written."""
+        n = 0
+        for it in items:
+            obj = {f: _dotted_get(it, f) for f in self.fields} if (self.fields and isinstance(it, dict)) else it
+            sys.stdout.write(jsonlib.dumps(_jsonable(obj), ensure_ascii=False, default=str) + "\n")
+            sys.stdout.flush()
+            n += 1
+        return n
+
+    def message(self, text: str) -> None:
+        """A human status line (table mode only; suppressed in every machine format).
+
+        Allowlist, not denylist: `!= json` would also let this print into csv and
+        markdown, corrupting both. stdout is a machine channel (see AGENTS.md) —
+        only the one human-facing format may carry prose.
+        """
+        if self.fmt == OutputFormat.table:
+            self.console.print(text)
+
+    # ---- json --------------------------------------------------------
+    def _emit_json(self, data: Any) -> None:
+        sys.stdout.write(jsonlib.dumps(_jsonable(data), indent=2, ensure_ascii=False, default=str))
+        sys.stdout.write("\n")
+
+    # ---- table -------------------------------------------------------
+    def _emit_table(
+        self,
+        data: Any,
+        *,
+        columns: Sequence[Column] | None,
+        title: str | None,
+        empty: str,
+    ) -> None:
+        rows = data if isinstance(data, list) else [data] if isinstance(data, dict) else None
+        if rows is None:
+            self.console.print(str(data))
+            return
+        if not rows:
+            self.console.print(f"[dim]{empty}[/dim]")
+            return
+
+        if columns is None:
+            # key/value table for a single object, else fall back to JSON.
+            if len(rows) == 1 and isinstance(rows[0], dict):
+                self._kv_table(rows[0], title=title)
+                return
+            self._emit_json(data)
+            return
+
+        table = Table(title=title, show_lines=False, header_style="bold")
+        for header, _ in columns:
+            table.add_column(header)
+        for row in rows:
+            table.add_row(*[_fmt_cell(_accessor_value(row, acc)) for _, acc in columns])
+        self.console.print(table)
+
+    # ---- csv ---------------------------------------------------------
+    def _emit_csv(self, data: Any, *, columns) -> None:
+        rows = data if isinstance(data, list) else [data] if isinstance(data, dict) else None
+        if rows is None:
+            sys.stdout.write(str(data) + "\n")
+            return
+        writer = csvlib.writer(sys.stdout)
+        if columns:
+            writer.writerow([h for h, _ in columns])
+            for r in rows:
+                writer.writerow([_csv_cell(_accessor_value(r, acc)) for _, acc in columns])
+        elif rows and isinstance(rows[0], dict):
+            # union of keys preserves columns even if some rows omit a field
+            keys: list[str] = []
+            for r in rows:
+                for k in r:
+                    if k not in keys:
+                        keys.append(k)
+            writer.writerow(keys)
+            for r in rows:
+                writer.writerow([_csv_cell(r.get(k)) for k in keys])
+
+    # ---- markdown ----------------------------------------------------
+    def _emit_markdown(self, data: Any, *, columns, title, empty) -> None:
+        out = sys.stdout
+        if title:
+            out.write(f"### {title}\n\n")
+        rows = data if isinstance(data, list) else [data] if isinstance(data, dict) else None
+        if rows is None:
+            out.write(f"{data}\n")
+            return
+        if not rows:
+            out.write(f"_{empty}_\n")
+            return
+
+        if columns is not None:
+            headers = [h for h, _ in columns]
+            cells = [[_md_cell(_accessor_value(r, acc)) for _, acc in columns] for r in rows]
+            out.write(_md_table(headers, cells))
+            return
+        if len(rows) == 1 and isinstance(rows[0], dict):
+            # single object -> Field/Value table
+            cells = [[_md_cell(k), _md_cell(v)] for k, v in rows[0].items()]
+            out.write(_md_table(["Field", "Value"], cells))
+            return
+        # list without a column spec -> fenced JSON (still valid markdown)
+        out.write("```json\n")
+        out.write(jsonlib.dumps(_jsonable(data), indent=2, ensure_ascii=False, default=str))
+        out.write("\n```\n")
+
+    def _kv_table(self, obj: dict, *, title: str | None) -> None:
+        table = Table(title=title, show_header=False, box=None)
+        table.add_column("field", style="bold cyan")
+        table.add_column("value")
+        for key, value in obj.items():
+            table.add_row(key, _fmt_cell(value))
+        self.console.print(table)
+
+
+def print_error(err: Any, fmt: OutputFormat) -> None:
+    """Render an error to stderr in the active format."""
+    if fmt == OutputFormat.json:
+        from .errors import OpError
+
+        payload = err.to_dict() if isinstance(err, OpError) else {"error": str(err)}
+        _err_console.file.write(jsonlib.dumps(payload, indent=2, ensure_ascii=False, default=str) + "\n")
+    else:
+        _err_console.print(f"[red]error:[/red] {err}")
+
+
+def _dotted_get(row: Any, path: str) -> Any:
+    """Fetch a possibly-nested value by dotted path, e.g. ``assignee.name``."""
+    cur = row
+    for part in path.split("."):
+        if isinstance(cur, dict):
+            cur = cur.get(part)
+        else:
+            return None
+    return cur
+
+
+def _project(data: Any, fields: Sequence[str]) -> Any:
+    """Keep only the selected fields (dotted paths allowed). The dotted string is
+    used as the output key so the projection is flat and predictable."""
+    if isinstance(data, list):
+        return [{f: _dotted_get(r, f) for f in fields} if isinstance(r, dict) else r for r in data]
+    if isinstance(data, dict):
+        return {f: _dotted_get(data, f) for f in fields}
+    return data
+
+
+def _csv_cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (dict, list)):
+        return jsonlib.dumps(value, ensure_ascii=False, default=str)
+    return str(value)
+
+
+def _md_cell(value: Any) -> str:
+    text = _fmt_cell(value)
+    # keep the table one row per record: escape pipes and flatten newlines
+    return text.replace("\\", "\\\\").replace("|", "\\|").replace("\n", "<br>")
+
+
+def _md_table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> str:
+    lines = ["| " + " | ".join(headers) + " |", "| " + " | ".join("---" for _ in headers) + " |"]
+    for row in rows:
+        lines.append("| " + " | ".join(row) + " |")
+    return "\n".join(lines) + "\n"
+
+
+def _jsonable(obj: Any) -> Any:
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return dataclasses.asdict(obj)
+    if isinstance(obj, enum.Enum):
+        return obj.value
+    return obj