elan-cli 0.1.0__py3-none-any.whl

elan_cli/__init__.py

@@ -0,0 +1,6 @@
+"""The developer-facing command line.
+
+THE ONLY BRANDED PACKAGE. Everything under `agentkit_*` is deliberately
+brand-free so a derived project renames nothing; this one is the product, so it
+is where the name lives.
+"""

elan_cli/adk.py

@@ -0,0 +1,197 @@
+"""`elan adk` — ADK's own tools, pointed at this repo.
+
+WHY A WRAPPER AND NOT JUST `adk web`. ADK's loader looks in
+`<agents_dir>/<name>/agent.py` for a module-level `app` or `root_agent`. A
+target here exports `MANIFEST` and `build(ctx)` and neither of those names,
+because the platform supplies the other half: `build_app` is what turns a
+`build()` into an ADK `App`, and in a pod the engine does it. So `adk web`
+against a tenant repo finds nothing and says so as "no agents", which reads as
+the repo being empty.
+
+THE SHIMS ARE GENERATED, NOT SCAFFOLDED INTO THE REPO. The obvious fix is to
+append eight lines to every `agent.py`, and it works — but those lines run AT
+IMPORT, and `elan validate` and the build's manifest export both import target
+modules to read their MANIFEST. That makes every deploy build a whole App to
+answer a question about a dataclass, and the day a `build()` needs something
+only a laptop has, the BUILD breaks at manifest export naming nothing useful.
+Generated modules keep the target files exporting exactly what the contract
+says.
+
+WHAT YOU GET IS THE REAL STACK, which is the point. The shim calls the same
+`build_plugins` a pod does, so `adk web` runs the agent behind the autonomy
+gate, the typing plugin and the observability plugin. The ledger is absent
+because `LEDGER_SERVICE_URL` is unset, and it says so rather than pretending:
+"running unbilled (local dev only)".
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from elan_cli.manifests import ManifestError, interpreter
+from elan_cli.manifests import read as read_manifests
+from elan_cli.project import Project, ProjectError, find
+
+#: Under a dot directory so it never looks like part of the repo, and never
+#: collides with `agents/` — which ADK would otherwise ALSO scan, finding the
+#: real modules, failing to load them, and reporting both.
+SHIM_ROOT = Path(".elan") / "adk"
+
+#: Commands that take a directory of agents as their last positional.
+DIRECTORY_COMMANDS = {"web", "api_server"}
+
+#: Commands that take ONE agent, named by slug.
+TARGET_COMMANDS = {"run"}
+
+SHIM = '''\
+"""GENERATED by `elan adk` for {slug}. Rewritten on every run; do not edit.
+
+The whole file exists to give ADK's loader the name it looks for. Everything
+it does is what the runtime does at pod start, so what you drive here is the
+agent as deployed rather than a stripped-down copy of it.
+"""
+
+from pathlib import Path
+
+from agentkit_runtime.builder import build_app
+from agentkit_runtime.config import Settings
+from agentkit_runtime.plugins import build_plugins
+from agentkit_runtime.registry import resolve
+
+# PASSED, NOT INHERITED. `Settings` would otherwise read TARGETS_ROOT from the
+# environment, and `adk` is started from wherever the developer happens to be.
+_settings = Settings(targets_root=Path(r"{root}"))
+_target = resolve({slug!r}, _settings)
+_plugins, _ = build_plugins(_target, _settings,
+                            _target.version_stamp(_settings.build_sha))
+
+# `app`, WHICH ADK CHECKS FOR BEFORE `root_agent`. The App carries the plugin
+# stack; a bare root_agent would run the agent with none of it.
+app = build_app(_target, _settings, plugins=_plugins)
+'''
+
+#: A directory that ignores itself, so this works in a repo whose .gitignore
+#: predates `elan init` — which is every repo scaffolded before this existed.
+SELF_IGNORE = "*\n"
+
+
+def module_name(slug: str) -> str:
+    """The directory ADK will import this target as.
+
+    SLUGS CONTAIN HYPHENS AND MODULE NAMES CANNOT. ADK imports the DIRECTORY
+    NAME — `importlib.import_module(f"{name}.agent")` — so a shim directory
+    called `fish-facts` is a SyntaxError-shaped import failure rather than an
+    agent. Same substitution `elan new` already makes for the module it
+    scaffolds, so the two agree.
+    """
+    return slug.replace("-", "_")
+
+
+def generate(project: Project, slugs: list[str]) -> Path:
+    """Write one shim per target. Returns the directory to point ADK at."""
+    root = project.root / SHIM_ROOT
+    # REMOVED FIRST, so a target that was deleted or renamed does not linger
+    # and get served alongside the ones that still exist.
+    if root.exists():
+        shutil.rmtree(root)
+    root.mkdir(parents=True)
+    (project.root / ".elan" / ".gitignore").write_text(SELF_IGNORE)
+
+    for slug in slugs:
+        package = root / module_name(slug)
+        package.mkdir()
+        # A REGULAR PACKAGE, not a namespace one. Without this the directory
+        # is still importable, and also shadowable by anything else on the
+        # path with the same name.
+        (package / "__init__.py").write_text("")
+        (package / "agent.py").write_text(
+            SHIM.format(slug=slug, root=project.targets_root))
+    return root
+
+
+def argv_for(args: list[str], root: Path, slugs: list[str]) -> list[str]:
+    """What to pass ADK, given what the developer typed.
+
+    TWO RULES AND A PASSTHROUGH, deliberately not a general rewriter. Anything
+    cleverer — substituting every argument that happens to match a slug, say —
+    would eventually rewrite a filename or an option value, and a wrapper that
+    edits arguments unpredictably is worse than one that does nothing.
+    """
+    if not args:
+        return []
+    command = args[0]
+    if command in DIRECTORY_COMMANDS:
+        # APPENDED, so any option the developer passed still applies.
+        return [*args, str(root)]
+    if command in TARGET_COMMANDS and len(args) > 1:
+        # ONLY AN EXACT SLUG IS REPLACED. The slug they typed is the one the
+        # platform uses everywhere else; the directory is its module-safe
+        # spelling, which is an implementation detail they should not have to
+        # know.
+        return [command, *(str(root / module_name(a)) if a in slugs else a
+                           for a in args[1:])]
+    return list(args)
+
+
+def run(args: list[str], start: Path | None = None,
+        python: str | None = None) -> int:
+    if not args:
+        print("error: `elan adk` passes its arguments to ADK's own CLI.\n\n"
+              "  elan adk web          the dev UI, every target in this repo\n"
+              "  elan adk run <slug>   one target, in the terminal\n"
+              "  elan adk --help       everything else ADK offers")
+        return 2
+
+    try:
+        project = find(start)
+    except ProjectError as exc:
+        print(f"error: {exc}")
+        return 2
+
+    chosen, why = interpreter(project.targets_root, python)
+    # THE SAME INTERPRETER, so `adk` sees the repo's dependencies. A globally
+    # installed `adk` would import the tenant's modules with whatever happened
+    # to be on PATH, and fail on their first third-party import.
+    adk = Path(chosen).parent / "adk"
+    if not adk.exists():
+        print(f"error: no `adk` beside {chosen}\n({why})\n\n"
+              "ADK comes with the platform runtime, so this usually means the\n"
+              "environment was never created:\n\n"
+              "  elan env")
+        return 2
+
+    try:
+        manifests = read_manifests(project.targets_root, python=python)
+    except ManifestError as exc:
+        print(f"error: {exc}")
+        return 2
+
+    slugs = sorted(m["slug"] for m in manifests)
+    if not slugs:
+        print("error: this repo declares no targets, so there is nothing to run.")
+        return 2
+
+    root = generate(project, slugs)
+    print(f"targets  {', '.join(slugs)}")
+    print(f"shims    {root}")
+
+    argv = [str(adk), *argv_for(args, root, slugs)]
+    print(f"running  {' '.join(argv[1:])}")
+    print(flush=True)
+    return subprocess.run(argv, cwd=project.root, env=_environment()).returncode
+
+
+def _environment() -> dict[str, str]:
+    """ADK's own environment, plus the one thing it must not inherit.
+
+    `TARGET_SLUG` NAMES WHICH AGENT A POD RUNS, and a developer who has it set
+    — from a `.env`, or from having run the runtime by hand — would get that
+    one target for every shim, because `Settings` reads it. The shim passes
+    its slug explicitly; removing this makes sure nothing overrides it.
+    """
+    env = dict(os.environ)
+    env.pop("TARGET_SLUG", None)
+    return env

elan_cli/auth.py

@@ -0,0 +1,391 @@
+"""`elan login` — the device flow, and where the refresh token lives.
+
+A DEVICE FLOW BECAUSE A TERMINAL HAS NO REDIRECT URI. The CLI asks the issuer
+for a code, prints a URL and a short user code, and polls until a human has
+approved it in whatever browser they already have — possibly on another machine
+entirely, which is the case that makes this better than a loopback redirect.
+
+NOT A PERSONAL ACCESS TOKEN, which is what most tools reach for. A PAT is a
+long-lived bearer secret that has to be pasted, ends up in a shell history and
+a dotfile, and carries its owner's whole authority until somebody remembers to
+revoke it. This yields a short-lived access token and a refresh token.
+
+THE REFRESH TOKEN GOES TO THE OS KEYRING AND NEVER TO A FILE. That is the one
+non-negotiable part: a token under `~/.config` is readable by every process
+that runs as the developer, backed up to wherever their home directory is
+backed up, and synced to whatever syncs it.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass
+
+import httpx
+from elan_agentkit_contracts.oauth import token_scope
+
+from elan_cli.config import Config
+
+#: What the keyring entry is called. Stable, because changing it orphans every
+#: credential already stored rather than migrating it.
+logger = logging.getLogger(__name__)
+
+KEYRING_SERVICE = "elan-cli"
+
+def scopes(config: Config) -> str:
+    """What to ask the issuer for, MOSTLY ANSWERED BY THE PLATFORM.
+
+    `offline_access` IS THE CLI'S OWN and is not in the served scope: it is what
+    makes the issuer return a refresh token at all, and without it every command
+    an hour later needs a browser again. A `client_credentials` caller must not
+    ask for it, so it is added here rather than published to everybody.
+
+    THE REST IS `token_scope` FROM `GET /v1/auth`, including the audience term
+    that says who the token is FOR — without which it is addressed to nobody in
+    particular and the service's audience check can never pass. Composed locally
+    only against a platform that predates the field.
+    """
+    base = config.token_scope or token_scope(config.audience)
+    return f"{base} offline_access"
+
+
+class AuthError(Exception):
+    """Something about signing in, phrased for the person at the terminal."""
+
+
+@dataclass(frozen=True, slots=True)
+class Tokens:
+    access_token: str
+    refresh_token: str
+    #: Unix time. Compared with a margin rather than exactly — see `valid`.
+    expires_at: float
+
+    @property
+    def valid(self) -> bool:
+        """A MARGIN, NOT AN EXACT COMPARISON. A token that expires during the
+        request it was attached to fails as a 401 the CLI cannot distinguish
+        from a revoked session, so it is refreshed while it still works."""
+        return time.time() < self.expires_at - 60
+
+
+def _keyring():
+    try:
+        import keyring
+    except ImportError as exc:  # pragma: no cover - depends on the install
+        raise AuthError(
+            "the `keyring` package is not installed, and the CLI will not "
+            "write a credential to a file instead. Install it with "
+            "`pip install keyring`."
+        ) from exc
+    return keyring
+
+
+def store(issuer: str, refresh_token: str) -> None:
+    """Keep the refresh token, and DROP ANY CACHED ACCESS TOKEN WITH IT.
+
+    A rotated refresh token means a new session; an access token minted under
+    the previous one is not obviously invalid and would be used until it
+    expired. Writing one without clearing the other is how a cache outlives
+    the thing it was derived from.
+    """
+    _keyring().set_password(KEYRING_SERVICE, issuer, refresh_token)
+    _forget_access(issuer)
+
+
+def stored(issuer: str) -> str | None:
+    return _keyring().get_password(KEYRING_SERVICE, issuer)
+
+
+# ── THE ACCESS TOKEN IS CACHED TOO, AND THAT IS A LATENCY FIX ──────────────
+#
+# `Api.token()` holds its tokens on the INSTANCE, so a fresh process always
+# starts with none — and every `elan` command therefore paid a full OAuth
+# refresh before doing any work: a keyring read, a TLS handshake to the
+# issuer and a round trip, on `invoke`, on `agents`, on `status`. Measured at
+# roughly a second, every time, against a command whose own work is one API
+# call.
+#
+# `Tokens.valid` already existed and had nothing persisted to check against.
+#
+# SAME KEYRING, AND NO WEAKER FOR IT. The refresh token is already there and
+# is the stronger credential — it MINTS access tokens, for as long as the
+# session lives, while an access token expires on its own. Anything that can
+# read one can read the other.
+_ACCESS_SUFFIX = "#access"
+
+
+def _access_key(issuer: str) -> str:
+    return f"{issuer}{_ACCESS_SUFFIX}"
+
+
+def cache_access(issuer: str, tokens: Tokens) -> None:
+    """Remember an access token until it expires."""
+    try:
+        _keyring().set_password(
+            KEYRING_SERVICE, _access_key(issuer),
+            json.dumps({"access_token": tokens.access_token,
+                        "expires_at": tokens.expires_at}))
+    except Exception:  # noqa: BLE001
+        # A CACHE THAT CANNOT BE WRITTEN IS NOT AN ERROR, it is a slow
+        # command. Some keyring backends are read-only or locked, and
+        # refusing to run would trade a second of latency for an outage.
+        logger.debug("could not cache the access token", exc_info=True)
+
+
+def cached_access(issuer: str) -> Tokens | None:
+    """The cached access token, if there is one and it is still good."""
+    try:
+        raw = _keyring().get_password(KEYRING_SERVICE, _access_key(issuer))
+    except Exception:  # noqa: BLE001
+        return None
+    if not raw:
+        return None
+    try:
+        held = json.loads(raw)
+        found = Tokens(access_token=held["access_token"], refresh_token="",
+                       expires_at=float(held["expires_at"]))
+    except (ValueError, KeyError, TypeError):
+        # A CACHE THAT CANNOT BE READ IS A CACHE MISS. The format may have
+        # changed under an older CLI; refreshing is always correct.
+        return None
+    return found if found.valid else None
+
+
+def _forget_access(issuer: str) -> None:
+    try:
+        keyring = _keyring()
+        if keyring.get_password(KEYRING_SERVICE, _access_key(issuer)):
+            keyring.delete_password(KEYRING_SERVICE, _access_key(issuer))
+    except Exception:  # noqa: BLE001
+        logger.debug("could not clear the cached access token", exc_info=True)
+
+
+def forget(issuer: str) -> bool:
+    """`elan logout`. BOTH CREDENTIALS, or the session outlives the logout:
+    a cached access token keeps working until it expires, which is the one
+    thing somebody signing out is asking not to happen."""
+    keyring = _keyring()
+    _forget_access(issuer)
+    if keyring.get_password(KEYRING_SERVICE, issuer) is None:
+        return False
+    keyring.delete_password(KEYRING_SERVICE, issuer)
+    return True
+
+
+def platform_auth(api: str, *, client: httpx.Client | None = None) -> dict:
+    """Ask the PLATFORM where to sign in.
+
+    ONE URL INSTEAD OF FOUR FLAGS. A developer cannot be expected to know a
+    generated OIDC project id, and every value this returns is public anyway:
+    the issuer and audience appear in every token minted, and a public client's
+    id is public by construction — a secret shipped in every copy of a CLI is
+    not a secret.
+    """
+    owned = client is None
+    client = client or httpx.Client(timeout=30.0)
+    try:
+        response = client.get(f"{api}/v1/auth")
+    except httpx.HTTPError as exc:
+        raise AuthError(f"cannot reach {api}: {exc}") from exc
+    finally:
+        if owned:
+            client.close()
+
+    if response.status_code == 503:
+        raise AuthError(
+            f"{api} is not finished being set up — it has no sign-in "
+            "configuration yet. That is a platform-side problem, not "
+            "something this CLI can work around."
+        )
+    if response.status_code == 404:
+        raise AuthError(
+            f"{api} does not look like an Elan platform: it has no /v1/auth. "
+            "Check the URL."
+        )
+    if response.status_code != 200:
+        raise AuthError(
+            f"{api} answered HTTP {response.status_code} when asked where to "
+            f"sign in: {response.text[:200]}")
+    payload = response.json()
+    missing = [f for f in ("issuer", "client_id") if not payload.get(f)]
+    if missing:
+        raise AuthError(
+            f"{api} answered without {', '.join(missing)}, so there is "
+            "nothing to sign in against.")
+    return payload
+
+
+def discover(config: Config, *, client: httpx.Client | None = None) -> dict:
+    """The issuer's own endpoints, asked for rather than assumed.
+
+    Hardcoding `/oauth/v2/device_authorization` would work against this issuer
+    and silently fail against any other — and the discovery document exists so
+    a client never has to guess.
+    """
+    owned = client is None
+    client = client or httpx.Client(timeout=30.0)
+    try:
+        response = client.get(f"{config.issuer}/.well-known/openid-configuration")
+        if response.status_code != 200:
+            raise AuthError(
+                f"{config.issuer} did not serve a discovery document "
+                f"(HTTP {response.status_code}). Is the issuer right?"
+            )
+        return response.json()
+    except httpx.HTTPError as exc:
+        raise AuthError(f"cannot reach {config.issuer}: {exc}") from exc
+    finally:
+        if owned:
+            client.close()
+
+
+def begin(config: Config, *, client: httpx.Client | None = None) -> dict:
+    """Ask for a device code. Returns the issuer's response verbatim."""
+    document = discover(config, client=client)
+    endpoint = document.get("device_authorization_endpoint")
+    if not endpoint:
+        raise AuthError(
+            f"{config.issuer} does not advertise a device authorization "
+            "endpoint, so `elan login` cannot work against it. The CLI needs "
+            "one because a terminal has no redirect URI."
+        )
+    owned = client is None
+    client = client or httpx.Client(timeout=30.0)
+    try:
+        response = client.post(endpoint, data={
+            "client_id": config.client_id,
+            "scope": scopes(config),
+        })
+        if response.status_code >= 400:
+            raise AuthError(
+                f"the issuer refused the device request "
+                f"(HTTP {response.status_code}): {response.text[:300]}\n"
+                "  A 400 here usually means the CLI's client id is not "
+                "configured for the device_code grant."
+            )
+        payload = response.json()
+        payload["_token_endpoint"] = document["token_endpoint"]
+        return payload
+    except httpx.HTTPError as exc:
+        raise AuthError(f"cannot reach {endpoint}: {exc}") from exc
+    finally:
+        if owned:
+            client.close()
+
+
+def poll(config: Config, device: dict, *, client: httpx.Client | None = None,
+         sleep=time.sleep, now=time.monotonic) -> Tokens:
+    """Wait for the human, honouring the issuer's OWN pacing.
+
+    `interval` AND `slow_down` ARE NOT OPTIONAL. Polling faster than the issuer
+    asked earns a `slow_down`, and ignoring that earns a refusal — so a login
+    that polled on a fixed timer would work until the issuer was busy and then
+    fail in a way nobody could reproduce.
+    """
+    owned = client is None
+    client = client or httpx.Client(timeout=30.0)
+    interval = float(device.get("interval", 5))
+    deadline = now() + float(device.get("expires_in", 300))
+    try:
+        while now() < deadline:
+            sleep(interval)
+            response = client.post(device["_token_endpoint"], data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": device["device_code"],
+                "client_id": config.client_id,
+            })
+            payload = response.json() if response.content else {}
+            if response.status_code == 200:
+                return _tokens(payload)
+
+            error = payload.get("error", "")
+            if error == "authorization_pending":
+                continue
+            if error == "slow_down":
+                # The issuer's instruction, followed rather than noted.
+                interval += 5
+                continue
+            if error == "access_denied":
+                raise AuthError("the request was denied in the browser.")
+            if error == "expired_token":
+                break
+            raise AuthError(
+                f"the issuer refused the token request: "
+                f"{error or response.status_code} "
+                f"{payload.get('error_description', '')}".strip()
+            )
+        raise AuthError(
+            "the login expired before it was approved. Run `elan login` again."
+        )
+    finally:
+        if owned:
+            client.close()
+
+
+def refresh(config: Config, refresh_token: str, *,
+            client: httpx.Client | None = None) -> Tokens:
+    """Trade a refresh token for a fresh access token.
+
+    A FAILURE HERE IS NOT AN ERROR TO RETRY. A refresh token is rejected
+    because the session was revoked, the token was rotated, or it expired — all
+    of which mean the same thing to the developer, which is that they have to
+    sign in again. So the message says that rather than reporting an OAuth
+    error code.
+    """
+    document = discover(config, client=client)
+    owned = client is None
+    client = client or httpx.Client(timeout=30.0)
+    try:
+        response = client.post(document["token_endpoint"], data={
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": config.client_id,
+            "scope": scopes(config),
+        })
+        if response.status_code != 200:
+            raise AuthError("your session is no longer valid. Run `elan login`.")
+        return _tokens(response.json())
+    except httpx.HTTPError as exc:
+        raise AuthError(f"cannot reach the issuer: {exc}") from exc
+    finally:
+        if owned:
+            client.close()
+
+
+def _tokens(payload: dict) -> Tokens:
+    access = payload.get("access_token", "")
+    if access.count(".") != 2:
+        # THE TRAP ADR-0049 RECORDED, caught on the client side too. Zitadel
+        # issues OPAQUE tokens unless the application asks for JWTs, and an
+        # opaque token fails at the verifier as MALFORMED — which reads like a
+        # CLI bug rather than an application setting. Saying it here names the
+        # actual cause.
+        raise AuthError(
+            "the issuer returned an OPAQUE access token, not a JWT. The "
+            "services verify locally against the published keys and cannot "
+            "verify an opaque string. The CLI's application needs "
+            "`accessTokenType: JWT`."
+        )
+    return Tokens(
+        access_token=access,
+        refresh_token=payload.get("refresh_token", ""),
+        expires_at=time.time() + float(payload.get("expires_in", 3600)),
+    )
+
+
+def claims(access_token: str) -> dict:
+    """The token's payload, DECODED AND NOT VERIFIED.
+
+    Used only to show a developer who they are signed in as. The CLI has no
+    business verifying a token it did not have to trust — the SERVICE verifies,
+    against the issuer's published keys, and that is the check that matters. A
+    second verification here would imply this one was load-bearing.
+    """
+    import base64
+    import json
+
+    payload = access_token.split(".")[1]
+    payload += "=" * (-len(payload) % 4)
+    return json.loads(base64.urlsafe_b64decode(payload))