paradigx-cli-core 0.1.0__tar.gz

paradigx_cli_core-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+# Python build / test artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/

paradigx_cli_core-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: paradigx-cli-core
+Version: 0.1.0
+Summary: Shared core for Paradigx product CLIs — OAuth device-flow, token cache, HTTP client
+Project-URL: Homepage, https://github.com/jiangjin11/paradigx-workspace
+Author: Paradigx Pte Ltd
+License: MIT
+Keywords: agent,cli,device-flow,oauth,paradigx
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# paradigx-cli-core
+
+Shared core for [Paradigx](https://github.com/jiangjin11/paradigx-workspace)
+product CLIs (`botu`, `tokenroute`, ...).
+
+This is a **library, not a CLI** — it has no command entry point. Product
+CLIs depend on it and keep only their command layer.
+
+## What it provides
+
+- **OAuth device-flow** login against Logto (`auth`, `device_flow`)
+- **Shared token cache** at `~/.paradigx/auth.json`, keyed by API URL, so
+  one login is reused across every Paradigx CLI (`config`)
+- **Automatic JWT refresh** — cached tokens are transparently renewed via
+  the stored refresh token (`auth.valid_access_token`)
+- **HTTP client** with per-product trailing-slash / redirect handling
+  (`client`)
+- **`--json` output helpers** — rich tables for humans, JSON for agents
+  (`output`)
+
+## Usage (by a product CLI)
+
+```python
+from paradigx_cli_core import do_login, valid_access_token, request
+
+# login
+do_login("https://botu.io/api/auth/discovery/", "https://botu.io",
+         on_code=lambda c: print("visit", c.verification_uri_complete))
+
+# authenticated call (auto-refreshes the token)
+token = valid_access_token("https://botu.io")
+sites = request("GET", "https://botu.io", "/api/sites",
+                token=token, trailing_slash=True)
+```
+
+See `docs/specs/cli-phase-b.md` in the workspace repo for the design.
+
+---
+
+© 2026 Paradigx. All Rights Reserved.

paradigx_cli_core-0.1.0/README.md

@@ -0,0 +1,40 @@
+# paradigx-cli-core
+
+Shared core for [Paradigx](https://github.com/jiangjin11/paradigx-workspace)
+product CLIs (`botu`, `tokenroute`, ...).
+
+This is a **library, not a CLI** — it has no command entry point. Product
+CLIs depend on it and keep only their command layer.
+
+## What it provides
+
+- **OAuth device-flow** login against Logto (`auth`, `device_flow`)
+- **Shared token cache** at `~/.paradigx/auth.json`, keyed by API URL, so
+  one login is reused across every Paradigx CLI (`config`)
+- **Automatic JWT refresh** — cached tokens are transparently renewed via
+  the stored refresh token (`auth.valid_access_token`)
+- **HTTP client** with per-product trailing-slash / redirect handling
+  (`client`)
+- **`--json` output helpers** — rich tables for humans, JSON for agents
+  (`output`)
+
+## Usage (by a product CLI)
+
+```python
+from paradigx_cli_core import do_login, valid_access_token, request
+
+# login
+do_login("https://botu.io/api/auth/discovery/", "https://botu.io",
+         on_code=lambda c: print("visit", c.verification_uri_complete))
+
+# authenticated call (auto-refreshes the token)
+token = valid_access_token("https://botu.io")
+sites = request("GET", "https://botu.io", "/api/sites",
+                token=token, trailing_slash=True)
+```
+
+See `docs/specs/cli-phase-b.md` in the workspace repo for the design.
+
+---
+
+© 2026 Paradigx. All Rights Reserved.

paradigx_cli_core-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "paradigx-cli-core"
+version = "0.1.0"
+description = "Shared core for Paradigx product CLIs — OAuth device-flow, token cache, HTTP client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Paradigx Pte Ltd" }]
+keywords = ["cli", "oauth", "device-flow", "agent", "paradigx"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "httpx>=0.28",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3",
+    "pytest-mock>=3.14",
+]
+
+[project.urls]
+Homepage = "https://github.com/jiangjin11/paradigx-workspace"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/paradigx_cli_core"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

paradigx_cli_core-0.1.0/src/paradigx_cli_core/__init__.py

@@ -0,0 +1,63 @@
+"""paradigx-cli-core — shared core for Paradigx product CLIs.
+
+Provides OAuth device-flow login, a shared `~/.paradigx/auth.json` token
+cache, automatic JWT refresh, an HTTP client, and `--json` output helpers.
+Product CLIs (botu, tokenroute, ...) depend on this and keep only their
+command layer. See docs/specs/cli-phase-b.md.
+"""
+from .client import ApiError, exit_code_for, request, with_trailing_slash
+from .config import (
+    Credentials,
+    clear_credentials,
+    default_config_dir,
+    import_legacy,
+    load_credentials,
+    save_credentials,
+)
+from .auth import NeedLogin, do_login, refresh, valid_access_token
+from .device_flow import (
+    DeviceCodeResponse,
+    DiscoveryInfo,
+    fetch_discovery,
+    open_browser,
+    poll_for_token,
+    request_device_code,
+)
+from .output import emit, error, info, is_json_mode, set_json_mode, success
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # client
+    "ApiError",
+    "exit_code_for",
+    "request",
+    "with_trailing_slash",
+    # config
+    "Credentials",
+    "clear_credentials",
+    "default_config_dir",
+    "import_legacy",
+    "load_credentials",
+    "save_credentials",
+    # auth
+    "NeedLogin",
+    "do_login",
+    "refresh",
+    "valid_access_token",
+    # device_flow
+    "DeviceCodeResponse",
+    "DiscoveryInfo",
+    "fetch_discovery",
+    "open_browser",
+    "poll_for_token",
+    "request_device_code",
+    # output
+    "emit",
+    "error",
+    "info",
+    "is_json_mode",
+    "set_json_mode",
+    "success",
+]

paradigx_cli_core-0.1.0/src/paradigx_cli_core/auth.py

@@ -0,0 +1,113 @@
+"""Login orchestration + automatic token refresh.
+
+`do_login` runs the full device-flow and persists credentials.
+`valid_access_token` is what command code calls before every API request:
+it returns a non-expired access token, transparently refreshing via the
+stored refresh_token when needed.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import replace
+
+import httpx
+
+from .config import Credentials, load_credentials, save_credentials
+from .device_flow import fetch_discovery, poll_for_token, request_device_code
+
+# Refresh when fewer than this many seconds of validity remain.
+_REFRESH_SKEW_SECONDS = 60
+
+
+class NeedLogin(RuntimeError):
+    """Raised when there's no usable credential and the user must log in."""
+
+    def __init__(self, message: str = "not logged in — run `login` first"):
+        super().__init__(message)
+
+
+def _token_endpoint(creds: Credentials) -> str | None:
+    """Resolve the OIDC token endpoint for a credential.
+
+    New logins store `token_endpoint` directly. Pre-Phase-B / legacy-imported
+    entries only have `issuer`; derive from it (botu issuer ends with `/oidc`,
+    tokenroute issuer doesn't).
+    """
+    if creds.token_endpoint:
+        return creds.token_endpoint
+    iss = (creds.issuer or "").rstrip("/")
+    if not iss:
+        return None
+    return f"{iss}/token" if iss.endswith("/oidc") else f"{iss}/oidc/token"
+
+
+def refresh(creds: Credentials) -> Credentials:
+    """Exchange the stored refresh_token for a fresh access token.
+
+    Raises NeedLogin if the credential can't be refreshed (no refresh_token,
+    endpoint unknown, or the IdP rejects it).
+    """
+    endpoint = _token_endpoint(creds)
+    if not creds.refresh_token or not creds.client_id or not endpoint:
+        raise NeedLogin("session expired — run `login` again")
+    data = {
+        "grant_type": "refresh_token",
+        "refresh_token": creds.refresh_token,
+        "client_id": creds.client_id,
+    }
+    if creds.resource:
+        data["resource"] = creds.resource
+    try:
+        with httpx.Client(timeout=15.0) as c:
+            r = c.post(endpoint, data=data)
+    except httpx.RequestError as e:
+        raise NeedLogin(f"could not reach auth server to refresh: {e}") from e
+    if not r.is_success:
+        raise NeedLogin("session expired — run `login` again")
+    tok = r.json()
+    return replace(
+        creds,
+        access_token=tok["access_token"],
+        refresh_token=tok.get("refresh_token") or creds.refresh_token,
+        expires_at=int(time.time()) + int(tok.get("expires_in", 3600)),
+    )
+
+
+def valid_access_token(api_url: str) -> str:
+    """Return a non-expired access token for `api_url`.
+
+    Auto-refreshes (and persists) when the cached token is within the skew
+    window of expiry. Raises NeedLogin if there's nothing usable.
+    """
+    creds = load_credentials(api_url)
+    if creds is None or not creds.access_token:
+        raise NeedLogin()
+    if creds.expires_at and creds.expires_at - time.time() < _REFRESH_SKEW_SECONDS:
+        creds = refresh(creds)
+        save_credentials(creds)
+    return creds.access_token
+
+
+def do_login(discovery_url: str, api_url: str, *, on_code=None) -> Credentials:
+    """Run the full OAuth device-flow and persist the result.
+
+    `on_code(DeviceCodeResponse)` is invoked once the user code is known —
+    the CLI uses it to print the verification URL and open a browser.
+    """
+    disc = fetch_discovery(discovery_url)
+    code = request_device_code(disc)
+    if on_code is not None:
+        on_code(code)
+    tok = poll_for_token(disc, code)
+    creds = Credentials(
+        access_token=tok["access_token"],
+        refresh_token=tok.get("refresh_token"),
+        expires_at=int(time.time()) + int(tok.get("expires_in", 3600)),
+        issuer=disc.issuer,
+        client_id=disc.client_id,
+        resource=disc.resource,
+        api_url=api_url,
+        token_endpoint=disc.token_endpoint,
+    )
+    save_credentials(creds)
+    return creds

paradigx_cli_core-0.1.0/src/paradigx_cli_core/client.py

@@ -0,0 +1,86 @@
+"""Thin HTTP client for Paradigx product APIs.
+
+`request()` is product-agnostic: the caller passes the base URL, the bearer
+token, and whether the API needs trailing slashes (botu-web is a Next.js
+app with `trailingSlash: true`; the tokenroute FastAPI gateway is not).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+def exit_code_for(err: ApiError) -> int:
+    """Map an ApiError onto a CLI exit code: 1 user / 2 network / 3 server."""
+    if err.status == 0:
+        return 2
+    return 1 if err.status < 500 else 3
+
+
+def with_trailing_slash(path: str) -> str:
+    """Ensure a `/` before any query string — for `trailingSlash: true` APIs."""
+    base, sep, query = path.partition("?")
+    if not base.endswith("/"):
+        base += "/"
+    return f"{base}{sep}{query}"
+
+
+def _raise(resp: httpx.Response) -> None:
+    if resp.is_success:
+        return
+    try:
+        body = resp.json()
+    except (ValueError, httpx.DecodingError):
+        body = resp.text
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):  # {"error": {"message": ...}}
+            msg = err.get("message") or resp.reason_phrase
+        else:  # {"error": "...", "detail"?: "..."}
+            msg = err or body.get("detail") or body.get("message") or resp.reason_phrase
+            if err and body.get("detail"):
+                msg = f"{err} ({body['detail']})"
+    else:
+        msg = resp.reason_phrase
+    raise ApiError(resp.status_code, str(msg), body)
+
+
+def request(
+    method: str,
+    base_url: str,
+    path: str,
+    *,
+    token: str,
+    json_body: Any | None = None,
+    timeout: float = 30.0,
+    trailing_slash: bool = False,
+    follow_redirects: bool = True,
+    user_agent: str = "paradigx-cli-core",
+) -> Any:
+    """Call a product API endpoint with a bearer token. Returns parsed JSON."""
+    if trailing_slash:
+        path = with_trailing_slash(path)
+    headers = {
+        "User-Agent": user_agent,
+        "Accept": "application/json",
+        "Authorization": f"Bearer {token}",
+    }
+    url = f"{base_url.rstrip('/')}{path}"
+    try:
+        with httpx.Client(timeout=timeout, follow_redirects=follow_redirects) as client:
+            resp = client.request(method, url, json=json_body, headers=headers)
+    except httpx.RequestError as e:
+        raise ApiError(0, f"network error: {e}") from e
+    _raise(resp)
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()

paradigx_cli_core-0.1.0/src/paradigx_cli_core/config.py

@@ -0,0 +1,160 @@
+"""Shared credential storage for Paradigx product CLIs.
+
+Tokens live in ``~/.paradigx/auth.json`` — shared across every Paradigx
+CLI (botu, tokenroute, ...). They all authenticate against the same Logto,
+so a single login is reused. Entries are keyed by Logto resource indicator
+(so multiple products / envs coexist); retrieval picks the entry whose
+``api_url`` matches the current target.
+
+auth.json shape::
+
+    { "version": 1,
+      "tokens": {
+        "<resource>": { access_token, refresh_token, expires_at, issuer,
+                        client_id, resource, api_url, token_endpoint } } }
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+_CRED_FIELDS = (
+    "access_token",
+    "refresh_token",
+    "expires_at",
+    "issuer",
+    "client_id",
+    "resource",
+    "api_url",
+    "token_endpoint",
+)
+
+
+def default_config_dir() -> Path:
+    return Path.home() / ".paradigx"
+
+
+def _auth_path() -> Path:
+    return default_config_dir() / "auth.json"
+
+
+@dataclass
+class Credentials:
+    access_token: str
+    refresh_token: str | None = None
+    expires_at: int | None = None  # unix seconds
+    issuer: str | None = None
+    client_id: str | None = None
+    resource: str | None = None
+    api_url: str | None = None
+    token_endpoint: str | None = None  # OIDC token endpoint, for refresh
+
+
+def _read_store() -> dict:
+    p = _auth_path()
+    if not p.exists():
+        return {"version": 1, "tokens": {}}
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {"version": 1, "tokens": {}}
+    if not isinstance(data, dict):
+        return {"version": 1, "tokens": {}}
+    if not isinstance(data.get("tokens"), dict):
+        data["tokens"] = {}
+    data.setdefault("version", 1)
+    return data
+
+
+def _write_store(store: dict) -> None:
+    d = default_config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    p = _auth_path()
+    p.write_text(json.dumps(store, indent=2), encoding="utf-8")
+    # Owner-only on POSIX; near no-op on Windows but doesn't error.
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+
+def save_credentials(creds: Credentials) -> Path:
+    store = _read_store()
+    key = creds.resource or creds.api_url or "default"
+    store["tokens"][key] = {f: getattr(creds, f) for f in _CRED_FIELDS}
+    _write_store(store)
+    return _auth_path()
+
+
+def load_credentials(api_url: str) -> Credentials | None:
+    """Return the stored credential whose ``api_url`` matches."""
+    store = _read_store()
+    matches = [
+        v for v in store["tokens"].values() if isinstance(v, dict) and v.get("api_url") == api_url
+    ]
+    if not matches:
+        return None
+    best = max(matches, key=lambda v: v.get("expires_at") or 0)
+    return Credentials(**{f: best.get(f) for f in _CRED_FIELDS})
+
+
+def clear_credentials(api_url: str) -> bool:
+    """Drop credential(s) for ``api_url``. True if anything was removed."""
+    store = _read_store()
+    kept = {
+        k: v
+        for k, v in store["tokens"].items()
+        if not (isinstance(v, dict) and v.get("api_url") == api_url)
+    }
+    if len(kept) == len(store["tokens"]):
+        return False
+    store["tokens"] = kept
+    _write_store(store)
+    return True
+
+
+def import_legacy(
+    legacy_path: Path,
+    api_url: str,
+    *,
+    token_endpoint: str | None = None,
+    resource: str | None = None,
+) -> bool:
+    """Migrate a pre-Phase-B single-credential file into the shared store.
+
+    Used by tokenroute 0.2.0 to pull ``~/.tokenroute/credentials.json`` into
+    ``~/.paradigx/auth.json``. No-op if the legacy file is absent or this
+    api_url already has an entry. The legacy file is left in place (so a
+    downgrade to 0.1.0 still works).
+
+    `resource` is a fallback for legacy files that predate the field — it's
+    required for the OIDC token endpoint to mint JWT (not opaque) access
+    tokens on refresh, so the caller must supply its product's resource
+    indicator when the legacy file may lack one.
+    """
+    if not legacy_path.exists():
+        return False
+    if load_credentials(api_url) is not None:
+        return False
+    try:
+        data = json.loads(legacy_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return False
+    if not isinstance(data, dict) or not data.get("access_token"):
+        return False
+    save_credentials(
+        Credentials(
+            access_token=data.get("access_token", ""),
+            refresh_token=data.get("refresh_token"),
+            expires_at=data.get("expires_at"),
+            issuer=data.get("issuer"),
+            client_id=data.get("client_id"),
+            resource=data.get("resource") or resource,
+            api_url=api_url,
+            token_endpoint=token_endpoint,
+        )
+    )
+    return True

paradigx_cli_core-0.1.0/src/paradigx_cli_core/device_flow.py

@@ -0,0 +1,129 @@
+"""OIDC device-flow client — talks directly to Logto.
+
+The product CLI passes its discovery URL (a product endpoint that returns
+``{issuer, client_id, resource, scopes, device_authorization_endpoint,
+token_endpoint}``). The CLI never hardcodes a Logto URL. This is the
+OIDC-standard pattern: the client connects to the IdP, the resource server
+only validates tokens.
+"""
+from __future__ import annotations
+
+import time
+import webbrowser
+from dataclasses import dataclass
+
+import httpx
+
+# Per RFC 8628 §3.5 we honour the server's `interval`; this is a sane floor.
+_MIN_POLL_INTERVAL_SECONDS = 5
+
+
+@dataclass
+class DiscoveryInfo:
+    issuer: str
+    client_id: str
+    resource: str
+    scopes: list[str]
+    device_authorization_endpoint: str
+    token_endpoint: str
+
+
+@dataclass
+class DeviceCodeResponse:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+def fetch_discovery(discovery_url: str) -> DiscoveryInfo:
+    """GET the product's auth-discovery endpoint."""
+    with httpx.Client(timeout=10.0, follow_redirects=True) as c:
+        r = c.get(discovery_url)
+    r.raise_for_status()
+    data = r.json()
+    return DiscoveryInfo(
+        issuer=data["issuer"],
+        client_id=data["client_id"],
+        resource=data["resource"],
+        scopes=data["scopes"],
+        device_authorization_endpoint=data["device_authorization_endpoint"],
+        token_endpoint=data["token_endpoint"],
+    )
+
+
+def request_device_code(disc: DiscoveryInfo) -> DeviceCodeResponse:
+    """POST {device_authorization_endpoint} → device_code + user_code."""
+    with httpx.Client(timeout=10.0) as c:
+        r = c.post(
+            disc.device_authorization_endpoint,
+            data={
+                "client_id": disc.client_id,
+                "scope": " ".join(disc.scopes),
+                "resource": disc.resource,
+            },
+        )
+    r.raise_for_status()
+    body = r.json()
+    return DeviceCodeResponse(
+        device_code=body["device_code"],
+        user_code=body["user_code"],
+        verification_uri=body["verification_uri"],
+        verification_uri_complete=body.get(
+            "verification_uri_complete", body["verification_uri"]
+        ),
+        expires_in=body["expires_in"],
+        interval=max(body.get("interval", 5), _MIN_POLL_INTERVAL_SECONDS),
+    )
+
+
+def open_browser(url: str) -> bool:
+    """Best-effort. False on headless environments with no display."""
+    try:
+        return webbrowser.open(url)
+    except webbrowser.Error:
+        return False
+
+
+def poll_for_token(disc: DiscoveryInfo, code: DeviceCodeResponse, *, on_pending=None) -> dict:
+    """Poll {token_endpoint} until success / expired / denied.
+
+    Returns the raw token response dict. Raises RuntimeError with a
+    human-readable message on failure.
+    """
+    deadline = time.time() + code.expires_in
+    interval = code.interval
+    with httpx.Client(timeout=10.0) as client:
+        while time.time() < deadline:
+            time.sleep(interval)
+            r = client.post(
+                disc.token_endpoint,
+                data={
+                    "client_id": disc.client_id,
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": code.device_code,
+                    "resource": disc.resource,
+                },
+            )
+            if r.is_success:
+                return r.json()
+            err = (
+                r.json().get("error")
+                if r.headers.get("content-type", "").startswith("application/json")
+                else None
+            )
+            if err == "authorization_pending":
+                if on_pending is not None:
+                    on_pending()
+                continue
+            if err == "slow_down":
+                interval += 5
+                continue
+            if err == "expired_token":
+                raise RuntimeError("device code expired — log in again")
+            if err == "access_denied":
+                raise RuntimeError("login denied by user")
+            raise RuntimeError(f"token exchange failed ({r.status_code}): {r.text}")
+    raise RuntimeError("device code expired before user completed login")

paradigx_cli_core-0.1.0/src/paradigx_cli_core/output.py

@@ -0,0 +1,76 @@
+"""Output helpers — toggle between human-friendly rich tables and --json.
+
+JSON mode is process-global, set by the product CLI's Typer callback via
+`set_json_mode()` and read everywhere via `is_json_mode()`.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+_JSON_ENV = "_PARADIGX_CLI_JSON"
+_console = Console()
+_err_console = Console(stderr=True)
+
+
+def set_json_mode(enabled: bool) -> None:
+    if enabled:
+        os.environ[_JSON_ENV] = "1"
+    else:
+        os.environ.pop(_JSON_ENV, None)
+
+
+def is_json_mode() -> bool:
+    return os.environ.get(_JSON_ENV) == "1"
+
+
+def emit(payload: Any, *, table_columns: list[tuple[str, str]] | None = None) -> None:
+    """Print `payload` as JSON (agent mode) or a rich table / kv list (human).
+
+    `table_columns` is a list of `(header, dict_key)` pairs used when payload
+    is a list. Single dicts render as a key/value list.
+    """
+    if is_json_mode():
+        print(json.dumps(payload, indent=2, default=str))
+        return
+
+    if isinstance(payload, list) and table_columns:
+        table = Table(show_header=True, header_style="bold")
+        for header, _ in table_columns:
+            table.add_column(header)
+        for row in payload:
+            table.add_row(*[str(row.get(k, "")) for _, k in table_columns])
+        _console.print(table)
+        return
+
+    if isinstance(payload, dict):
+        for k, v in payload.items():
+            _console.print(f"[bold]{k}[/bold]: {v}")
+        return
+
+    _console.print(payload)
+
+
+def info(msg: str) -> None:
+    if not is_json_mode():
+        _console.print(msg)
+
+
+def success(msg: str) -> None:
+    if not is_json_mode():
+        # ASCII-safe marker — Windows legacy GBK consoles can't encode U+2713.
+        _console.print(f"[green]OK[/green] {msg}")
+
+
+def error(msg: str, *, code: int = 1) -> None:
+    """Print an error and exit. code: 1 user / 2 network / 3 server."""
+    if is_json_mode():
+        print(json.dumps({"error": msg}, indent=2))
+    else:
+        _err_console.print(f"[red]error[/red]: {msg}")
+    sys.exit(code)

paradigx_cli_core-0.1.0/tests/test_core.py

@@ -0,0 +1,265 @@
+"""Tests for paradigx-cli-core.
+
+`Path.home` is redirected to tmp_path so the real ~/.paradigx/ is never
+touched; httpx is monkeypatched so no real network calls happen.
+"""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from paradigx_cli_core import auth as auth_mod
+from paradigx_cli_core import client as client_mod
+from paradigx_cli_core import config as config_mod
+from paradigx_cli_core import output as output_mod
+from paradigx_cli_core.config import Credentials
+
+
+@pytest.fixture
+def fake_home(tmp_path, monkeypatch):
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    return tmp_path
+
+
+@pytest.fixture(autouse=True)
+def _clean_json_mode(monkeypatch):
+    monkeypatch.delenv("_PARADIGX_CLI_JSON", raising=False)
+
+
+def _mock_httpx(monkeypatch, *, status=200, json_body=None):
+    """Patch httpx.Client so .post / .request return a canned response."""
+    import httpx
+
+    resp = MagicMock(spec=httpx.Response)
+    resp.is_success = 200 <= status < 300
+    resp.status_code = status
+    resp.json.return_value = json_body or {}
+    resp.text = json.dumps(json_body) if json_body is not None else ""
+    resp.content = (resp.text or "x").encode()
+    resp.headers = {"content-type": "application/json"}
+    resp.reason_phrase = "OK" if resp.is_success else "Error"
+
+    client = MagicMock()
+    client.__enter__ = MagicMock(return_value=client)
+    client.__exit__ = MagicMock(return_value=False)
+    client.post = MagicMock(return_value=resp)
+    client.request = MagicMock(return_value=resp)
+    monkeypatch.setattr("httpx.Client", lambda **kw: client)
+    return client
+
+
+# ─── config ──────────────────────────────────────────────────────────
+
+
+def test_credentials_roundtrip(fake_home):
+    config_mod.save_credentials(
+        Credentials(access_token="abc", refresh_token="r", expires_at=123,
+                    resource="res-1", api_url="https://botu.io")
+    )
+    loaded = config_mod.load_credentials("https://botu.io")
+    assert loaded.access_token == "abc"
+    assert loaded.refresh_token == "r"
+    assert loaded.resource == "res-1"
+
+
+def test_load_none_when_empty(fake_home):
+    assert config_mod.load_credentials("https://botu.io") is None
+
+
+def test_store_separates_by_api_url(fake_home):
+    config_mod.save_credentials(
+        Credentials(access_token="botu-tok", resource="r1", api_url="https://botu.io")
+    )
+    config_mod.save_credentials(
+        Credentials(access_token="tr-tok", resource="r2", api_url="https://api.tokenroute.io")
+    )
+    assert config_mod.load_credentials("https://botu.io").access_token == "botu-tok"
+    assert config_mod.load_credentials("https://api.tokenroute.io").access_token == "tr-tok"
+
+
+def test_clear_credentials(fake_home):
+    config_mod.save_credentials(Credentials(access_token="x", resource="r", api_url="https://botu.io"))
+    assert config_mod.clear_credentials("https://botu.io") is True
+    assert config_mod.load_credentials("https://botu.io") is None
+    assert config_mod.clear_credentials("https://botu.io") is False
+
+
+def test_import_legacy(fake_home, tmp_path):
+    legacy = tmp_path / "credentials.json"
+    legacy.write_text(json.dumps({
+        "access_token": "old-tok", "refresh_token": "old-ref",
+        "expires_at": 999, "issuer": "https://auth.paradigx.com", "client_id": "c1",
+    }), encoding="utf-8")
+    assert config_mod.import_legacy(
+        legacy, "https://api.tokenroute.io", token_endpoint="https://auth.paradigx.com/oidc/token"
+    ) is True
+    got = config_mod.load_credentials("https://api.tokenroute.io")
+    assert got.access_token == "old-tok"
+    assert got.token_endpoint == "https://auth.paradigx.com/oidc/token"
+    # idempotent — second call is a no-op
+    assert config_mod.import_legacy(legacy, "https://api.tokenroute.io") is False
+
+
+def test_import_legacy_missing_file(fake_home, tmp_path):
+    assert config_mod.import_legacy(tmp_path / "nope.json", "https://botu.io") is False
+
+
+def test_import_legacy_resource_fallback(fake_home, tmp_path):
+    # pre-0.2 files predate the `resource` field — the caller supplies it so
+    # refresh keeps minting JWT (not opaque) tokens.
+    legacy = tmp_path / "credentials.json"
+    legacy.write_text(
+        json.dumps({"access_token": "t", "refresh_token": "r", "issuer": "https://i"}),
+        encoding="utf-8",
+    )
+    config_mod.import_legacy(
+        legacy, "https://api.tokenroute.io", resource="https://api.tokenroute.io"
+    )
+    got = config_mod.load_credentials("https://api.tokenroute.io")
+    assert got.resource == "https://api.tokenroute.io"
+
+
+# ─── auth: token endpoint resolution + refresh ───────────────────────
+
+
+def test_token_endpoint_prefers_stored():
+    c = Credentials(access_token="x", token_endpoint="https://e/token", issuer="https://i")
+    assert auth_mod._token_endpoint(c) == "https://e/token"
+
+
+def test_token_endpoint_derives_botu_style():
+    # botu issuer already ends with /oidc
+    c = Credentials(access_token="x", issuer="https://auth.paradigx.com/oidc")
+    assert auth_mod._token_endpoint(c) == "https://auth.paradigx.com/oidc/token"
+
+
+def test_token_endpoint_derives_tokenroute_style():
+    # tokenroute issuer has no /oidc
+    c = Credentials(access_token="x", issuer="https://auth.paradigx.com")
+    assert auth_mod._token_endpoint(c) == "https://auth.paradigx.com/oidc/token"
+
+
+def test_refresh_success(fake_home, monkeypatch):
+    _mock_httpx(monkeypatch, status=200, json_body={"access_token": "new-tok", "expires_in": 3600})
+    creds = Credentials(access_token="old", refresh_token="r", client_id="c",
+                        token_endpoint="https://e/token", api_url="https://botu.io")
+    out = auth_mod.refresh(creds)
+    assert out.access_token == "new-tok"
+    assert out.refresh_token == "r"  # kept when response omits a new one
+    assert out.expires_at > time.time()
+
+
+def test_refresh_rejected_raises_needlogin(fake_home, monkeypatch):
+    _mock_httpx(monkeypatch, status=400, json_body={"error": "invalid_grant"})
+    creds = Credentials(access_token="old", refresh_token="r", client_id="c",
+                        token_endpoint="https://e/token")
+    with pytest.raises(auth_mod.NeedLogin):
+        auth_mod.refresh(creds)
+
+
+def test_refresh_no_refresh_token_raises():
+    with pytest.raises(auth_mod.NeedLogin):
+        auth_mod.refresh(Credentials(access_token="x", token_endpoint="https://e/token"))
+
+
+# ─── auth: valid_access_token ────────────────────────────────────────
+
+
+def test_valid_access_token_fresh(fake_home):
+    config_mod.save_credentials(Credentials(
+        access_token="fresh", expires_at=int(time.time()) + 3600, api_url="https://botu.io"))
+    assert auth_mod.valid_access_token("https://botu.io") == "fresh"
+
+
+def test_valid_access_token_none_raises(fake_home):
+    with pytest.raises(auth_mod.NeedLogin):
+        auth_mod.valid_access_token("https://botu.io")
+
+
+def test_valid_access_token_expired_refreshes(fake_home, monkeypatch):
+    config_mod.save_credentials(Credentials(
+        access_token="stale", refresh_token="r", client_id="c",
+        token_endpoint="https://e/token",
+        expires_at=int(time.time()) - 10, api_url="https://botu.io"))
+    _mock_httpx(monkeypatch, status=200, json_body={"access_token": "refreshed", "expires_in": 3600})
+    assert auth_mod.valid_access_token("https://botu.io") == "refreshed"
+    # persisted
+    assert config_mod.load_credentials("https://botu.io").access_token == "refreshed"
+
+
+# ─── auth: do_login ──────────────────────────────────────────────────
+
+
+def test_do_login(fake_home, monkeypatch):
+    from paradigx_cli_core.device_flow import DeviceCodeResponse, DiscoveryInfo
+
+    disc = DiscoveryInfo(
+        issuer="https://auth.paradigx.com/oidc", client_id="cli", resource="res",
+        scopes=["openid"], device_authorization_endpoint="https://e/device",
+        token_endpoint="https://auth.paradigx.com/oidc/token")
+    code = DeviceCodeResponse("dc", "USER-1", "https://v", "https://v?c=1", 600, 5)
+    monkeypatch.setattr(auth_mod, "fetch_discovery", lambda u: disc)
+    monkeypatch.setattr(auth_mod, "request_device_code", lambda d: code)
+    monkeypatch.setattr(auth_mod, "poll_for_token", lambda d, c: {
+        "access_token": "jwt", "refresh_token": "rt", "expires_in": 3600})
+
+    seen = []
+    creds = auth_mod.do_login("https://botu.io/api/auth/discovery/", "https://botu.io",
+                              on_code=lambda c: seen.append(c.user_code))
+    assert seen == ["USER-1"]
+    assert creds.access_token == "jwt"
+    assert creds.token_endpoint == "https://auth.paradigx.com/oidc/token"
+    assert config_mod.load_credentials("https://botu.io").access_token == "jwt"
+
+
+# ─── client ──────────────────────────────────────────────────────────
+
+
+def test_with_trailing_slash():
+    assert client_mod.with_trailing_slash("/api/sites") == "/api/sites/"
+    assert client_mod.with_trailing_slash("/api/sites/") == "/api/sites/"
+    assert client_mod.with_trailing_slash("/api/usage?site=s") == "/api/usage/?site=s"
+
+
+def test_exit_code_for():
+    assert client_mod.exit_code_for(client_mod.ApiError(0, "net")) == 2
+    assert client_mod.exit_code_for(client_mod.ApiError(404, "nf")) == 1
+    assert client_mod.exit_code_for(client_mod.ApiError(500, "boom")) == 3
+
+
+def test_request_success(monkeypatch):
+    _mock_httpx(monkeypatch, status=200, json_body={"ok": True})
+    out = client_mod.request("GET", "https://botu.io", "/api/sites", token="t", trailing_slash=True)
+    assert out == {"ok": True}
+
+
+def test_request_error_raises_apierror(monkeypatch):
+    _mock_httpx(monkeypatch, status=404, json_body={"error": "not_found", "detail": "no site"})
+    with pytest.raises(client_mod.ApiError) as ei:
+        client_mod.request("GET", "https://botu.io", "/api/sites/x", token="t")
+    assert ei.value.status == 404
+    assert "not_found" in ei.value.message and "no site" in ei.value.message
+
+
+# ─── output ──────────────────────────────────────────────────────────
+
+
+def test_json_mode_toggle():
+    assert output_mod.is_json_mode() is False
+    output_mod.set_json_mode(True)
+    assert output_mod.is_json_mode() is True
+    output_mod.set_json_mode(False)
+    assert output_mod.is_json_mode() is False
+
+
+def test_emit_json(capsys):
+    output_mod.set_json_mode(True)
+    try:
+        output_mod.emit({"a": 1})
+    finally:
+        output_mod.set_json_mode(False)
+    assert json.loads(capsys.readouterr().out.strip()) == {"a": 1}