"""Terminal output helpers.

Every command prints either a human readable block or, with ``--json``, a single
JSON document on stdout so an agent can parse it.  Errors go to stderr (and to a
JSON object on stdout when ``--json`` is active) so stdout stays machine safe.
"""

import json
import sys


class Out:
    def __init__(self, as_json=False):
        self.as_json = as_json

    def json(self, payload):
        print(json.dumps(payload, indent=2, ensure_ascii=False))

    def data(self, payload, human=None):
        """Print ``payload`` as JSON, or ``human()`` when not in JSON mode."""
        if self.as_json:
            self.json(payload)
        elif human:
            human()

    def line(self, text=""):
        if not self.as_json:
            print(text)

    def notice(self, text):
        """Progress/warning for humans; goes to stderr so stdout stays parseable."""
        print(text, file=sys.stderr)

    def progress(self, text):
        """In-place progress line; suppressed in JSON mode."""
        if not self.as_json:
            print(text, end="\r", flush=True)

    def progress_done(self):
        if not self.as_json:
            print()

    def error(self, message):
        if self.as_json:
            self.json({"error": str(message)})
        print(f"❌ {message}", file=sys.stderr)