tai42-cli 1.0.0__py3-none-any.whl

tai42_cli/app.py

@@ -0,0 +1,281 @@
+"""The unified ``tai`` command.
+
+One Typer app exposes the remote command groups — thin clients over a tai42
+server's ``/api/*`` routes — plus the CLI-native ``completion`` and ``version``
+commands. The console entry point ``app`` is the compiled click group.
+
+Server-side and local commands (``serve``, ``db``, ``doctor``, ``backend`` …)
+are contributed by the server package through the ``tai.commands`` entry-point
+group: each entry point loads to a ``register(group: click.Group) -> None``
+callable that mounts its commands onto the compiled root group. When only this
+client is installed those commands are simply absent; the remote surface stands
+on its own.
+
+Registration lives here so each remote command module only fills its own Typer
+app without editing this file. An extension's ``register`` receives the compiled
+click group and may use click's own API on it, plus the two exported helpers:
+:func:`inject_json_flag` (give a Typer-backed leaf the trailing ``--json`` form)
+and :func:`mount_launcher` (mount a click launcher command under a name). The
+seams the command bodies build on are the
+:class:`~tai42_cli.context.AppContext` on the Typer context (for a configured
+client), :class:`~tai42_cli.client.ApiClient`, and the
+:mod:`tai42_cli.render` helpers.
+"""
+
+import os
+from importlib.metadata import entry_points
+from typing import Any, cast
+
+import click
+import typer
+from dotenv import load_dotenv
+from typer.core import TyperGroup, TyperOption
+from typer.main import get_command
+
+from tai42_cli import completion, version
+from tai42_cli.client import ApiError
+from tai42_cli.commands import (
+    agents,
+    auth,
+    backup,
+    channels,
+    checkpoints,
+    config,
+    connectors,
+    conversations,
+    extensions,
+    fleet,
+    hooks,
+    interactions,
+    keys,
+    manifest,
+    mcp,
+    notifications,
+    obs,
+    plugins,
+    presets,
+    resources,
+    roles,
+    schedules,
+    scopes,
+    storage,
+    sub_mcp,
+    system,
+    templates,
+    tool_meta,
+    tools,
+    traces,
+)
+from tai42_cli.context import AppContext
+
+# The entry-point group a server package publishes to contribute its local and
+# runtime commands (``serve``/``db``/``doctor``/``backend`` …) to this CLI.
+_EXTENSION_GROUP = "tai.commands"
+
+
+class TaiCLIGroup(TyperGroup):
+    """Root group that bridges standard-``click`` outcomes into Typer's runner.
+
+    Typer bundles its own vendored copy of click, so Typer's runner only
+    recognises its vendored exception types. Contributed launcher commands (and
+    the native command modules) raise standard-``click`` exceptions, and remote
+    commands raise :class:`ApiError`. This override translates all of those into
+    Typer's own control-flow exceptions so they render cleanly — a server/usage
+    message on stderr with a non-zero exit — instead of a traceback."""
+
+    def invoke(self, ctx: Any) -> Any:
+        try:
+            return super().invoke(ctx)
+        except ApiError as exc:
+            typer.echo(f"Error: {exc}", err=True)
+            raise typer.Exit(1) from exc
+        except click.exceptions.Exit as exc:
+            raise typer.Exit(exc.exit_code) from exc
+        except click.exceptions.Abort as exc:
+            raise typer.Abort() from exc
+        except click.ClickException as exc:
+            typer.echo(f"Error: {exc.format_message()}", err=True)
+            raise typer.Exit(exc.exit_code) from exc
+
+
+def _apply_json_flag(ctx: click.Context, _param: click.Parameter, value: bool | None) -> bool | None:
+    """Merge a per-subcommand ``--json/--no-json`` into the shared context.
+
+    The root callback owns the flag-first form (``tai --json <cmd>``); this lets the
+    same flag ride AFTER the subcommand (``tai <cmd> --json``). ``value`` is ``None``
+    unless the flag was actually passed, so the root callback's setting stands when
+    the trailing flag is absent."""
+    if value is not None and isinstance(ctx.obj, AppContext):
+        ctx.obj.json_output = value
+    return value
+
+
+def _json_flag_option() -> TyperOption:
+    """A fresh trailing ``--json/--no-json`` flag that merges into the context.
+
+    Built as a :class:`TyperOption` so its parse handling matches the Typer context
+    the compiled commands run under (a raw ``click.Option`` reads a context attribute
+    Typer's vendored context does not carry)."""
+    return TyperOption(
+        param_decls=["--json/--no-json"],
+        is_flag=True,
+        default=None,
+        expose_value=False,
+        callback=_apply_json_flag,
+        help="Emit raw JSON instead of human tables.",
+    )
+
+
+def inject_json_flag(command: click.Command) -> None:
+    """Give a compiled command the trailing ``--json/--no-json`` form.
+
+    A group recurses into every subcommand so a leaf reached as ``tai <group> <cmd>``
+    accepts the flag in its own right (``tai tools list --json``), matching the root
+    callback's flag-first form; a single leaf command gets the flag directly. The flag
+    is only meaningful once, so groups keep the root form and only leaf commands carry
+    the trailing one.
+
+    A group is detected by its ``commands`` mapping rather than by ``isinstance`` —
+    Typer's compiled sub-groups are its own vendored ``Group`` type, not a
+    :class:`click.Group` subclass. Extensions apply this to their own Typer-backed
+    leaves after mounting them."""
+    subcommands = getattr(command, "commands", None)
+    if subcommands is not None:
+        for sub in subcommands.values():
+            inject_json_flag(cast(click.Command, sub))
+    else:
+        command.params.append(cast(click.Parameter, _json_flag_option()))
+
+
+def mount_launcher(group: click.Group, launcher: click.Command, name: str) -> None:
+    """Mount a click launcher command under its ``tai`` subcommand name.
+
+    The command's own ``name`` is the canonical subcommand name now, so it is set
+    here (the rich help lists commands by that name, not by the registration key).
+    Extensions use this to mount their raw click launcher commands onto the root
+    group."""
+    launcher.name = name
+    group.add_command(launcher)
+
+
+cli_app = typer.Typer(
+    name="tai",
+    cls=TaiCLIGroup,
+    help="Operate a tai42 server from the terminal.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@cli_app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(
+        False,
+        "--json/--no-json",
+        help="Emit raw JSON instead of human tables.",
+    ),
+    server: str | None = typer.Option(
+        None,
+        "--server",
+        metavar="URL",
+        help="Server base URL. Resolved: this flag -> TAI_SERVER_URL -> config.toml -> local default.",
+    ),
+    api_key_stdin: bool = typer.Option(
+        False,
+        "--api-key-stdin",
+        help=(
+            "Read the API key as one line from stdin. Resolved: this flag -> TAI_API_KEY -> "
+            "config.toml -> interactive prompt. There is no --api-key VALUE flag (a value leaks "
+            "via ps and shell history)."
+        ),
+    ),
+) -> None:
+    # Bootstrap a local ``.env`` once for the whole CLI so every subcommand — the
+    # remote client and any contributed launcher alike — sees it. ``TAI_CONFIG_MODE``
+    # is read straight from the environment (default ``file``), normalized and
+    # validated here so this client needs no server settings module. Under ``k8s`` the
+    # platform injects env directly and a local ``.env`` must not shadow it, so the
+    # load is skipped.
+    raw_mode = os.environ.get("TAI_CONFIG_MODE", "file")
+    config_mode = raw_mode.strip().lower()
+    if config_mode not in ("file", "k8s"):
+        raise typer.BadParameter(
+            f"Invalid TAI_CONFIG_MODE={raw_mode!r}. Must be one of: file, k8s",
+            param_hint="TAI_CONFIG_MODE",
+        )
+    if config_mode != "k8s":
+        load_dotenv()
+    ctx.obj = AppContext(json_output=json_output, server_override=server, api_key_stdin=api_key_stdin)
+
+
+# Remote command groups — thin clients over the ``/api/*`` routes.
+_REMOTE_GROUPS: list[tuple[typer.Typer, str]] = [
+    (tools.app, "tools"),
+    (presets.app, "presets"),
+    (agents.app, "agents"),
+    (extensions.app, "extensions"),
+    (connectors.app, "connectors"),
+    (conversations.app, "conversations"),
+    (hooks.app, "hooks"),
+    (channels.app, "channels"),
+    (checkpoints.app, "checkpoints"),
+    (notifications.app, "notifications"),
+    (storage.app, "storage"),
+    (resources.app, "resources"),
+    (fleet.app, "fleet"),
+    (manifest.app, "manifest"),
+    (mcp.app, "mcp"),
+    (sub_mcp.app, "sub-mcp"),
+    (templates.app, "templates"),
+    (config.app, "config"),
+    (keys.app, "keys"),
+    (scopes.app, "scopes"),
+    (roles.app, "roles"),
+    (auth.app, "auth"),
+    (backup.app, "backup"),
+    (schedules.app, "schedules"),
+    (obs.app, "obs"),
+    (plugins.app, "plugins"),
+    (traces.app, "traces"),
+    (interactions.app, "interactions"),
+    (system.app, "system"),
+    (tool_meta.app, "tool-meta"),
+]
+for group_app, group_name in _REMOTE_GROUPS:
+    cli_app.add_typer(group_app, name=group_name)
+
+# CLI-native pieces the remote client owns outright.
+cli_app.add_typer(completion.app, name="completion")
+cli_app.command(name="version")(version.version)
+
+
+def _discover_extensions(root: click.Group) -> None:
+    """Load every ``tai.commands`` entry point and let it register its commands.
+
+    Each entry point loads to a ``register(group: click.Group) -> None`` callable and
+    is invoked with the compiled root group. Entry points are processed in sorted
+    entry-point-name order so contributed help order is deterministic. A failing load
+    or a failing ``register`` propagates — a broken contribution is never swallowed."""
+    discovered = sorted(entry_points(group=_EXTENSION_GROUP), key=lambda ep: ep.name)
+    for ep in discovered:
+        register = ep.load()
+        register(root)
+
+
+def _build_app() -> click.Group:
+    """Compile the Typer app to a click group, give every native leaf the trailing
+    ``--json`` form, then let installed extensions contribute their commands."""
+    command = cast(click.Group, get_command(cli_app))
+    # Inject the trailing ``--json`` form onto the native tree BEFORE extensions run;
+    # each extension applies :func:`inject_json_flag` to its own Typer-backed leaves.
+    inject_json_flag(command)
+    _discover_extensions(command)
+    return command
+
+
+app = _build_app()
+
+
+if __name__ == "__main__":
+    app()

tai42_cli/client.py

@@ -0,0 +1,273 @@
+"""Shared HTTP client for the ``tai`` CLI's remote commands.
+
+Every remote command talks to the server's ``/api/*`` surface — the SAME
+routes the Studio calls — through this one client, so the envelope contract and
+authentication live in exactly one place.
+
+The wire contract:
+
+* the api key travels in the ``x-api-key`` header;
+* a success body is ``{"data": ...}`` and is unwrapped to the inner value;
+* a failure body is ``{"error": "<message>"}`` and, together with the HTTP
+  status, is raised as a typed :class:`ApiError` (401/404/409/400 each get their
+  own subclass so callers can distinguish them);
+* streaming runs are consumed frame by frame off an SSE response — never
+  buffered whole.
+"""
+
+import json
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+import httpx
+
+
+class ApiError(Exception):
+    """A non-2xx response from the server API.
+
+    ``message`` is the server's ``{"error": ...}`` text where present, else the
+    raw response body. ``status_code`` is the HTTP status.
+    """
+
+    def __init__(self, message: str, *, status_code: int) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+class AuthError(ApiError):
+    """A 401 — the request carried no API key the server would accept."""
+
+
+class NotFoundError(ApiError):
+    """A 404 — the addressed resource does not exist."""
+
+
+class ConflictError(ApiError):
+    """A 409 — the request conflicts with the current server state."""
+
+
+class BadRequestError(ApiError):
+    """A 400 — the server rejected the request payload."""
+
+
+_STATUS_ERRORS: dict[int, type[ApiError]] = {
+    400: BadRequestError,
+    401: AuthError,
+    404: NotFoundError,
+    409: ConflictError,
+}
+
+
+def _server_message(response: httpx.Response) -> str | None:
+    """The ``{"error": ...}`` message from a response body, or ``None`` when the
+    body is not the JSON error envelope."""
+    try:
+        body = response.json()
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if isinstance(body, Mapping):
+        error = body.get("error")
+        if isinstance(error, str):
+            return error
+    return None
+
+
+def _error_from_response(response: httpx.Response) -> ApiError:
+    status = response.status_code
+    message = _server_message(response) or response.text.strip()
+    if status == 401:
+        detail = message or "no valid API key was accepted by the server"
+        return AuthError(f"not authenticated: {detail}", status_code=401)
+    if not message:
+        message = f"HTTP {status}"
+    error_cls = _STATUS_ERRORS.get(status, ApiError)
+    return error_cls(message, status_code=status)
+
+
+def _unwrap(response: httpx.Response) -> Any:
+    """Return the ``data`` payload of a success response, raising on any failure
+    status or a malformed success envelope."""
+    if response.status_code >= 400:
+        raise _error_from_response(response)
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        body = response.json()
+    except (json.JSONDecodeError, ValueError) as exc:
+        # A 2xx whose body is not JSON (a proxy's HTML page, say) is as malformed as
+        # a missing ``data`` key — surface it as the same typed error, not a raw decode.
+        raise ApiError(
+            f"malformed success envelope (body is not JSON): {response.text!r}",
+            status_code=response.status_code,
+        ) from exc
+    if not isinstance(body, Mapping) or "data" not in body:
+        raise ApiError(
+            f"malformed success envelope (expected a 'data' key): {body!r}",
+            status_code=response.status_code,
+        )
+    return body["data"]
+
+
+def iter_sse_data(lines: Iterator[str]) -> Iterator[tuple[str | None, str]]:
+    """Yield ``(event, data)`` for each SSE frame from a line iterator.
+
+    The server emits one JSON object per frame as a single ``data:`` line
+    terminated by a blank line. A frame's type may ride INSIDE that JSON (the
+    agents/runs stream sends no ``event:`` line) OR arrive OUT OF BAND on an
+    ``event:`` line (the interactions stream), so the parser surfaces the
+    ``event:`` value when present and yields ``None`` for it otherwise.
+    Comment/keepalive lines (a leading ``:``) and any other SSE fields are
+    ignored; multi-line ``data:`` values are joined with newlines.
+    """
+    event: str | None = None
+    data_parts: list[str] = []
+    for line in lines:
+        if line == "":
+            if data_parts:
+                yield event, "\n".join(data_parts)
+            event = None
+            data_parts = []
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        value = value[1:] if value.startswith(" ") else value
+        if field == "data":
+            data_parts.append(value)
+        elif field == "event":
+            event = value
+    if data_parts:
+        yield event, "\n".join(data_parts)
+
+
+class ApiClient:
+    """A thin httpx wrapper that owns the api-key header and the envelope.
+
+    Construct with a ``base_url`` and an ``api_key``; inject ``transport`` in tests
+    to serve responses from a fake without any network. ``api_key=None`` builds an
+    ANONYMOUS client that sends no credential header — the one public door the CLI
+    calls (``tai auth claim`` exchanging a claim token, which the caller has no key for
+    yet); every other command passes a real key.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        # No key → no ``x-api-key`` header at all, so a public route is never handed a
+        # stale/wrong credential (which its always-public middleware would ignore, but a
+        # protected route would 401 on).
+        headers = {"x-api-key": api_key} if api_key is not None else {}
+        self._client = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+            headers=headers,
+        )
+
+    def __enter__(self) -> "ApiClient":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        response = self._client.request(method, path, json=json, params=params)
+        return _unwrap(response)
+
+    def request_raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Perform the auth'd request and return the RAW response, unwrapping no
+        envelope, but still raising the typed error on a failure status.
+
+        The download routes (a bare backup document, a CSV/JSON export) answer
+        outside the ``{"data": ...}`` envelope, so their callers read the body
+        directly while keeping this module's auth, base URL, and typed errors.
+        """
+        response = self._client.request(method, path, json=json, params=params)
+        if response.status_code >= 400:
+            raise _error_from_response(response)
+        return response
+
+    def get(self, path: str, *, params: Mapping[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return self.request("POST", path, json=json, params=params)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return self.request("PATCH", path, json=json, params=params)
+
+    def put(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return self.request("PUT", path, json=json, params=params)
+
+    def delete(self, path: str, *, params: Mapping[str, Any] | None = None) -> Any:
+        return self.request("DELETE", path, params=params)
+
+    def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Iterator[tuple[str | None, str]]:
+        """Yield each SSE frame as ``(event, data)`` from a streaming run, incrementally.
+
+        The response body is consumed frame by frame — a run's output reaches
+        the caller as it arrives, never after the whole run completes. ``event``
+        is the frame's out-of-band ``event:`` type when the server sends one (the
+        interactions stream) and ``None`` otherwise (the runs stream, whose type
+        rides inside the JSON ``data``). A failure status raises the typed error
+        before any frame is yielded.
+        """
+        with self._client.stream(
+            method,
+            path,
+            json=json,
+            params=params,
+            headers={"accept": "text/event-stream"},
+        ) as response:
+            if response.status_code >= 400:
+                response.read()
+                raise _error_from_response(response)
+            yield from iter_sse_data(response.iter_lines())

tai42_cli/commands/__init__.py

@@ -0,0 +1,5 @@
+"""Remote command groups — thin clients over a tai42 server's ``/api/*`` routes.
+
+Each module exposes a ``typer.Typer`` app named ``app`` that the root CLI
+registers as a subcommand group. The command bodies are added per domain.
+"""