nexla-cli 0.2.0__py3-none-any.whl

nexla_cli/__init__.py

@@ -0,0 +1,247 @@
+"""`nexla` — CLI client for the `/nexla/*` agent API.
+
+Set ``NEXLA_API_URL`` and ``NEXLA_TOKEN`` in the environment (or run
+``nexla login --service-key ...`` to obtain a token first).
+"""
+
+from __future__ import annotations
+
+import functools
+import json as jsonlib
+import sys
+from collections.abc import Callable
+from typing import Any
+
+import typer
+
+# Typer 0.12+ vendors its own private click fork rather than depending on
+# the standalone `click` package (confirmed: `click` isn't even installed
+# in this venv) -- these are the exception types Click itself raises while
+# *parsing* argv, before any command callback runs, so they can't be
+# caught by `_wrap_cli_error` (which only wraps callback bodies). Imported
+# from the private `_click` module because Typer doesn't re-export them
+# publicly; there is no other way to intercept a parse-time usage error.
+from typer._click.exceptions import NoArgsIsHelpError, UsageError
+
+from . import login as login_module
+from . import output as output_module
+from .errors import CliError
+from .resources import (
+    code_containers,
+    connectors,
+    context,
+    credentials,
+    flows,
+    mcp_servers,
+    metrics,
+    nexsets,
+    notifications,
+    orgs,
+    probe,
+    sinks,
+    sources,
+    tools,
+    toolsets,
+    transforms,
+    triage,
+    users,
+)
+from .schema import schema_app
+
+
+def _output_flag_from_argv() -> str | None:
+    """Scan ``sys.argv`` for an explicit ``--output``/``-o`` value.
+
+    ``_wrap_cli_error`` wraps each command callback directly, so it runs
+    *before* Typer builds ``ctx`` — it cannot read ``ctx.obj`` the way
+    command bodies can (see ``output.ctx_mode``). Falling back to scanning
+    ``sys.argv`` directly is the only way to honor an explicit flag at this
+    point; ``NEXLA_OUTPUT``/``OUTPUT_FORMAT`` env and TTY autodetection
+    still work normally via ``output.resolve_mode``.
+    """
+    argv = sys.argv[1:]
+    for i, arg in enumerate(argv):
+        if arg in ("--output", "-o") and i + 1 < len(argv):
+            return argv[i + 1]
+        for prefix in ("--output=", "-o="):
+            if arg.startswith(prefix):
+                return arg[len(prefix) :]
+    return None
+
+
+def _wrap_cli_error[F: Callable[..., Any]](fn: F) -> F:
+    """Map a :class:`CliError` raised by a command into ``typer.Exit``.
+
+    Typer 0.12+ vendors its own private click fork (``typer._click``), so a
+    ``CliError`` subclassing the standalone ``click`` package's
+    ``ClickException`` is *not* recognized by Typer's exception handling —
+    it would propagate as a generic exception and every failure would map
+    to exit code 1. Wrapping each command callback here keeps the mapping
+    correct regardless of which click Typer happens to vendor.
+
+    In ``json``/``ndjson`` output mode, the caught error is emitted to
+    stderr as ``{"error": e.envelope, "detail": e.message}``-shaped JSON
+    instead of the plain ``error: {message}`` line, so an agent parsing
+    stderr doesn't have to special-case error output. Exit code mapping is
+    unchanged either way.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except CliError as e:
+            mode = output_module.resolve_mode(_output_flag_from_argv())
+            if mode in ("json", "ndjson"):
+                envelope = {"error": e.envelope, "detail": e.message}
+                typer.echo(jsonlib.dumps(envelope, default=str), err=True)
+            else:
+                typer.echo(f"error: {e.message}", err=True)
+            raise typer.Exit(e.code) from e
+
+    return wrapper  # type: ignore[return-value]
+
+
+def _wrap_app_commands(sub_app: typer.Typer) -> None:
+    for cmd_info in sub_app.registered_commands:
+        if cmd_info.callback is not None:
+            cmd_info.callback = _wrap_cli_error(cmd_info.callback)
+    # `schema_app` (Phase 3) has no `registered_commands` at all -- its only
+    # entry point is a `@schema_app.callback(invoke_without_command=True)`,
+    # which Typer stores separately as `registered_callback`. Wrap that too
+    # so a `CliError` raised from a callback-only sub-app still maps to the
+    # right exit code instead of falling through as a generic exception.
+    if sub_app.registered_callback is not None and sub_app.registered_callback.callback is not None:
+        sub_app.registered_callback.callback = _wrap_cli_error(sub_app.registered_callback.callback)
+
+
+app = typer.Typer(
+    name="nexla",
+    no_args_is_help=True,
+    help="Nexla agent CLI. Set NEXLA_API_URL and NEXLA_TOKEN.",
+)
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    output: str | None = typer.Option(
+        None, "--output", "-o", help="table|json|ndjson (default: table on a TTY, json otherwise)"
+    ),
+    fields: str | None = typer.Option(
+        None, "--fields", help="Comma-separated field mask, e.g. 'id,name'"
+    ),
+    page_all: bool = typer.Option(
+        False, "--page-all", help="Stream every page as NDJSON instead of one page as a table/JSON"
+    ),
+) -> None:
+    """Global output options, available to every subcommand except `login`.
+
+    Stashed on ``ctx.obj`` rather than re-declared per command. `login`
+    doesn't read ``ctx.obj`` and is unaffected by these flags — it always
+    writes the bare token to stdout by design.
+    """
+    ctx.obj = {
+        "mode": output,
+        "fields": fields.split(",") if fields else None,
+        "page_all": page_all,
+    }
+
+
+app.command("login")(_wrap_cli_error(login_module.login))
+
+for _mod in (
+    sources,
+    sinks,
+    nexsets,
+    credentials,
+    flows,
+    transforms,
+    connectors,
+    probe,
+    toolsets,
+    tools,
+    mcp_servers,
+    context,
+    orgs,
+    code_containers,
+    metrics,
+    users,
+    notifications,
+    triage,
+):
+    _wrap_app_commands(_mod.app)
+    app.add_typer(_mod.app)
+
+_wrap_app_commands(schema_app)
+app.add_typer(schema_app)
+
+
+_GLOBAL_FLAGS_WITH_VALUE = ("--output", "-o", "--fields")
+_GLOBAL_FLAGS_BOOL = ("--page-all",)
+
+
+def _reorder_global_flags(argv: list[str]) -> list[str]:
+    """Let ``--output``/``--fields``/``--page-all`` appear anywhere in argv.
+
+    Typer/Click only recognize a parent group's options before the
+    subcommand name (``nexla --output json sources list``, not
+    ``nexla sources list --output json``) — every subcommand tree behaves
+    this way (docker, kubectl, git). Rather than duplicating these three
+    options onto all 17 resource modules, hoist them to the front of argv
+    before Typer ever parses it, so users can put them wherever feels
+    natural.
+    """
+    front: list[str] = []
+    rest: list[str] = []
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg in _GLOBAL_FLAGS_BOOL:
+            front.append(arg)
+            i += 1
+        elif arg in _GLOBAL_FLAGS_WITH_VALUE and i + 1 < len(argv):
+            front.extend([arg, argv[i + 1]])
+            i += 2
+        elif any(arg.startswith(f"{flag}=") for flag in _GLOBAL_FLAGS_WITH_VALUE):
+            front.append(arg)
+            i += 1
+        else:
+            rest.append(arg)
+            i += 1
+    return front + rest
+
+
+def main() -> None:
+    """Console-script entrypoint (``nexla = "nexla_cli:main"``).
+
+    Runs the Typer app with ``standalone_mode=False`` so a Click-level
+    parse error (e.g. ``--params`` on a command that never defined it) can
+    be caught here and get a hint pointing at ``--help``, instead of
+    Click's own generic "No such option" with nothing pointing you toward
+    the fix. Under ``standalone_mode=False``, Click returns the exit code
+    from ``app()`` instead of calling ``sys.exit`` itself (confirmed this
+    session) -- every existing ``CliError``-mapped exit code (via
+    ``_wrap_cli_error`` -> ``typer.Exit``) still comes back this way
+    unaffected; only genuine argv-parsing errors raise here.
+    """
+    sys.argv[1:] = _reorder_global_flags(sys.argv[1:])
+    try:
+        code = app(standalone_mode=False)
+    except NoArgsIsHelpError as e:
+        # Typer/Click already echoed the help text to stdout before this
+        # exception ever reaches us (confirmed this session) -- calling
+        # `.show()` here would print it a second time, and its override
+        # writes to stderr, moving that second copy off the stream a
+        # script piping bare `nexla`/`nexla <group>` output would expect.
+        raise SystemExit(e.exit_code) from None
+    except UsageError as e:
+        e.show()
+        typer.echo(
+            "Run 'nexla <command> --help' to see its exact options.", err=True
+        )
+        raise SystemExit(e.exit_code) from None
+    raise SystemExit(code or 0)
+
+
+__all__ = ["app", "main"]

nexla_cli/client.py

@@ -0,0 +1,130 @@
+"""Thin, synchronous httpx wrapper shared by every CLI command.
+
+The CLI is short-lived (one process per invocation) so there's no need for
+an async client or connection pooling across calls. Mirrors the API's own
+``{detail: {error, detail, nexla_request_id}}`` failure envelope and maps
+failures to :class:`nexla_cli.errors.CliError` / exit codes instead of
+raising ``httpx`` or FastAPI exceptions.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from .errors import EXIT, CliError
+
+
+def _base() -> str:
+    url = os.environ.get("NEXLA_API_URL")
+    if not url:
+        raise CliError(EXIT.CONFIG, "NEXLA_API_URL is not set")
+    return url.rstrip("/")
+
+
+def _token() -> str:
+    tok = os.environ.get("NEXLA_TOKEN")
+    if not tok:
+        raise CliError(EXIT.CONFIG, "NEXLA_TOKEN is not set")
+    return tok
+
+
+def auth_token() -> str:
+    """Public accessor for the bearer token, for other transports (e.g. mcp_client)."""
+    return _token()
+
+
+def _envelope(r: httpx.Response) -> dict[str, Any]:
+    """Extract the ``{error, detail, nexla_request_id}`` failure envelope.
+
+    ``/nexla/*`` routes raise ``HTTPException(detail=...)``, which FastAPI
+    serializes as ``{"detail": <whatever was passed>}``. ``detail`` may
+    itself be a dict (our common shape), a plain string, or (for 422s) a
+    list of Pydantic error objects.
+    """
+    try:
+        body = r.json()
+    except ValueError:
+        return {"error": r.text[:512]}
+    if not isinstance(body, dict):
+        return {"error": str(body)[:512]}
+    detail = body.get("detail", body)
+    if isinstance(detail, dict):
+        return detail
+    return {"error": str(detail)[:512] if detail is not None else r.text[:512]}
+
+
+def _message_from_envelope(envelope: dict[str, Any], *, fallback: str) -> str:
+    for key in ("detail", "error"):
+        val = envelope.get(key)
+        if isinstance(val, str) and val:
+            return val
+    return fallback
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json: Any = None,
+    require_auth: bool = True,
+) -> Any:
+    """Fire one HTTP request against ``NEXLA_API_URL`` and return decoded JSON.
+
+    Raises :class:`CliError` (never a raw ``httpx``/network exception) on
+    any non-2xx response, with ``EXIT.from_status`` mapping the upstream
+    status code to a stable CLI exit code.
+    """
+    headers: dict[str, str] = {}
+    if require_auth:
+        headers["Authorization"] = f"Bearer {_token()}"
+
+    with httpx.Client(base_url=_base(), timeout=30.0, headers=headers) as c:
+        try:
+            r = c.request(method, path, params=params, json=json)
+        except httpx.HTTPError as e:
+            raise CliError(EXIT.UPSTREAM, f"request failed: {e}") from e
+
+    if r.is_success:
+        if r.status_code == 204 or not r.content:
+            return None
+        try:
+            return r.json()
+        except ValueError:
+            return None
+
+    envelope = _envelope(r)
+    message = _message_from_envelope(envelope, fallback=f"HTTP {r.status_code}")
+    raise CliError(EXIT.from_status(r.status_code), message, envelope=envelope)
+
+
+def paginate(
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    per_page: int = 100,
+) -> Iterator[Any]:
+    """Stream every item across all pages without ever buffering the full set.
+
+    Drives the loop off the ``Page[T]`` envelope's own ``next_page`` key
+    (falsy means done) rather than a length heuristic on ``items`` — a
+    ``len(batch) < per_page`` check is wrong (a last page can legitimately
+    be exactly ``per_page`` long) and was flagged as a bug in review.
+    Forwards the full ``params`` dict on every call, only overriding
+    ``page``/``per_page``, so resource-specific filters (e.g. ``sources
+    list``'s ``connector``/``flow_id``) stay applied under ``--page-all``.
+    """
+    page: int = 1
+    while True:
+        data = request(
+            "GET", path, params={**(params or {}), "page": page, "per_page": per_page}
+        )
+        yield from data.get("items", [])
+        next_page = data.get("next_page")
+        if not next_page:
+            return
+        page = next_page

nexla_cli/dryrun.py

@@ -0,0 +1,119 @@
+"""``--dry-run`` — hand-rolled structural validation, zero mutating calls.
+
+Per the plan's resolved open question (§3 of
+``plans/2026-07-07-nexla-agent-phase-3-schema-safety-docs.md``): a full
+JSON-Schema validator (the ``jsonschema`` package) is not worth a new
+runtime dependency for schemas this flat. :func:`validate_body` checks two
+things only:
+
+- every key in ``schema["required"]`` is present in ``body``;
+- for keys present in both, a rough type check of ``schema["properties"]``
+  ``"type"`` (``string``/``integer``/``boolean``/``object``/``array``/
+  ``null``) against the Python value's type, including the
+  ``anyOf: [{type: X}, {type: "null"}]`` optional-field shape the live
+  API's generated schemas use for optional fields.
+
+Deliberately **not** implemented: ``pattern``/``format``/``enum``/
+``minimum``/nested-object validation — the real API still fully validates
+on any non-dry-run call, so an over-eager local validator would only give
+a false sense of safety for constraints this module doesn't check.
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+from typing import Any
+
+import typer
+
+from . import openapi_client
+from .errors import EXIT, CliError
+
+_JSON_TYPE_TO_PY: dict[str, type | tuple[type, ...]] = {
+    "string": str,
+    "integer": int,
+    "number": (int, float),
+    "boolean": bool,
+    "object": dict,
+    "array": list,
+    "null": type(None),
+}
+
+
+def _allowed_types(prop_schema: dict[str, Any]) -> list[str]:
+    """Collect the JSON-Schema ``type``(s) a property may take.
+
+    Handles a bare ``"type": "X"``, and the ``anyOf: [{type: X}, {type:
+    "null"}]`` shape the live API's generated schemas use for optional
+    fields — anything else in ``anyOf`` (a nested ``$ref``, for instance)
+    is skipped rather than guessed at, matching this module's documented
+    scope (rough type check only, not general schema resolution).
+    """
+    types: list[str] = []
+    if "type" in prop_schema and isinstance(prop_schema["type"], str):
+        types.append(prop_schema["type"])
+    for branch in prop_schema.get("anyOf", []):
+        if isinstance(branch, dict) and isinstance(branch.get("type"), str):
+            types.append(branch["type"])
+    return types
+
+
+def validate_body(schema: dict[str, Any], body: dict[str, Any]) -> list[str]:
+    """Return human-readable validation errors; empty list means valid."""
+    errors: list[str] = []
+    required = schema.get("required", [])
+    for key in required:
+        if key not in body or body[key] is None:
+            errors.append(f"missing required field: {key}")
+
+    properties: dict[str, Any] = schema.get("properties", {})
+    for key, value in body.items():
+        prop_schema = properties.get(key)
+        if not isinstance(prop_schema, dict):
+            continue
+        allowed = [t for t in _allowed_types(prop_schema) if t in _JSON_TYPE_TO_PY]
+        if not allowed:
+            continue
+        py_types: tuple[type, ...] = ()
+        for json_t in allowed:
+            mapped = _JSON_TYPE_TO_PY[json_t]
+            py_types += mapped if isinstance(mapped, tuple) else (mapped,)
+        if not isinstance(value, py_types):
+            errors.append(
+                f"field '{key}' expected type {'/'.join(allowed)}, got {type(value).__name__}"
+            )
+    return errors
+
+
+def run_dry_run(*, resource: str, verb: str, body: dict[str, Any]) -> None:
+    """Fetch the matching schema, validate ``body``, print result, and exit.
+
+    Called by a mutating command's ``--dry-run`` branch *before* it fires
+    its real ``client.request(...)`` call. Always exits the process (0 for
+    valid, 2 for invalid) — the caller never falls through to the real
+    mutating call after this returns, because it never returns.
+    """
+    spec = openapi_client.fetch_openapi()
+    match = openapi_client.resolve(spec, resource, verb)
+    if match is None:
+        # Route not found at all -- our hand-maintained ROUTES table has
+        # drifted from the live API, or this (resource, verb) pair was
+        # never wired up. Conservative fallback per the stuck-resource
+        # policy: refuse rather than guess.
+        raise CliError(EXIT.ERROR, "dry-run not supported for this command yet")
+
+    body_schema = openapi_client.request_body_schema(spec, match["operation"])
+    if body_schema is None:
+        # The route exists but genuinely takes no request body (e.g.
+        # `activate`/`pause`/`delete`/`sync`/`detach`) -- nothing to
+        # validate, so the body is trivially valid.
+        typer.echo(jsonlib.dumps({"valid": True, "body": body}, indent=2, default=str))
+        raise typer.Exit(EXIT.OK)
+
+    errors = validate_body(body_schema, body)
+    if errors:
+        typer.echo(jsonlib.dumps({"valid": False, "errors": errors}, indent=2), err=True)
+        raise typer.Exit(EXIT.VALIDATION)
+
+    typer.echo(jsonlib.dumps({"valid": True, "body": body}, indent=2, default=str))
+    raise typer.Exit(EXIT.OK)

nexla_cli/errors.py

@@ -0,0 +1,45 @@
+"""Exit-code taxonomy + the CLI's structured error exception.
+
+Agents branch on the numeric exit code, not on message text — keep this
+table stable and documented in ``--help`` epilogs.
+"""
+
+from __future__ import annotations
+
+
+class EXIT:
+    """Stable exit-code taxonomy for the `nexla` CLI."""
+
+    OK = 0
+    ERROR = 1  # generic / unexpected
+    VALIDATION = 2  # bad local input (Phase 2 validation, dry-run failures)
+    CONFIG = 3  # missing env / not configured
+    AUTH = 4  # 401/403 from the API
+    NOT_FOUND = 5  # 404
+    UPSTREAM = 6  # 5xx / 502 gateway
+
+    @staticmethod
+    def from_status(code: int) -> int:
+        if code in (401, 403):
+            return EXIT.AUTH
+        if code == 404:
+            return EXIT.NOT_FOUND
+        if code >= 500:
+            return EXIT.UPSTREAM
+        return EXIT.ERROR
+
+
+class CliError(Exception):
+    """Raised anywhere in the CLI to signal a specific exit code + message.
+
+    Every ``app.command()`` callback is wrapped (see
+    ``cli/__init__.py::_wrap_cli_error``) so this maps to ``typer.Exit(code)``
+    with the message on stderr, regardless of entrypoint (installed console
+    script or ``CliRunner.invoke`` in tests).
+    """
+
+    def __init__(self, code: int, message: str, *, envelope: dict | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.envelope = envelope

nexla_cli/login.py

@@ -0,0 +1,42 @@
+"""`nexla login` — exchange a Nexla service key for a session bearer.
+
+Not a ``resources/`` module: hits the bare API root (``POST /login``, no
+``/nexla`` prefix) — matches ``routers/auth.py::LoginRequest``/``LoginResponse``.
+Registered as a single top-level command, not a sub-typer group.
+"""
+
+from __future__ import annotations
+
+import os
+
+import typer
+
+from . import client
+from .sanitize import sanitize
+
+
+def login(
+    service_key: str = typer.Option(..., "--service-key", help="Nexla service key"),
+    api_url: str | None = typer.Option(
+        None, "--api-url", help="Override NEXLA_API_URL for this call"
+    ),
+) -> None:
+    """Exchange a service key for a bearer token.
+
+    Prints the access token to stdout only, so
+    ``export NEXLA_TOKEN=$(nexla login --service-key ...)`` works.
+    Everything else (expiry, user, org) goes to stderr.
+    """
+    if api_url:
+        os.environ["NEXLA_API_URL"] = api_url
+
+    resp = client.request("POST", "/login", json={"service_key": service_key}, require_auth=False)
+    # The token itself is never sanitized — it's a literal secret value
+    # that must round-trip exactly for `export NEXLA_TOKEN=$(...)` to work.
+    typer.echo(resp["access_token"])
+    user = sanitize(resp["user"])
+    org = sanitize(resp["org"])
+    typer.echo(
+        f"expires_at={resp['expires_at']} user={user['email']} org={org['name']}",
+        err=True,
+    )