elan-cli 0.1.0__py3-none-any.whl

elan_cli/tenant.py

@@ -0,0 +1,59 @@
+"""`elan tenant` — creating a customer, and listing the ones that exist.
+
+PLATFORM STAFF ONLY, AND THE CLI DOES NOT CHECK THAT. The service does, and
+saying no in two places means two places to disagree — the one that matters is
+the one holding the Zitadel credential. What this does is make the refusal
+legible: a 403 from the API is printed as the sentence the service wrote, which
+explains that a tenant cannot create another tenant.
+
+THIS IS NOT `elan init`. That scaffolds a repo for a customer who already
+exists; this creates the customer. They are adjacent in a developer's day and
+completely different in what they touch, which is why they are separate
+commands rather than flags of one.
+"""
+
+from __future__ import annotations
+
+from elan_cli.client import Api
+
+
+def create(api: Api, slug: str, display_name: str = "") -> int:
+    """Create a tenant and print what the person who runs this needs next."""
+    body = api.request("POST", "/v1/tenants",
+                       json={"slug": slug, "display_name": display_name})
+
+    if not body.get("created", True):
+        print(f"tenant {body['tenant']!r} already exists")
+    else:
+        print(f"created tenant {body['tenant']!r}")
+    print(f"  organisation  {body['org_id']}")
+    # THE AUDIENCE. Generated by Zitadel, different in every environment, and
+    # unknowable without asking — so it is printed here rather than left to be
+    # looked up by whoever wires a client next.
+    print(f"  audience      {body['project_id']}")
+
+    if body.get("created", True):
+        # THE ORG HAS NO USERS, and that is deliberate rather than missing.
+        # Creating one means choosing a password or sending an invitation, and
+        # both are decisions about who gets into a customer's account. Saying
+        # so beats leaving somebody to discover an empty tenant.
+        print()
+        print("  No users yet — the organisation is empty. Add the customer's")
+        print("  first administrator in Zitadel, in the organisation above.")
+    return 0
+
+
+def ls(api: Api) -> int:
+    tenants = api.request("GET", "/v1/tenants").get("tenants", [])
+    if not tenants:
+        print("no tenants")
+        return 0
+    width = max(len(t["slug"]) for t in tenants)
+    for tenant in tenants:
+        # FALLS BACK HERE, not in the record. A tenant with no display name is
+        # shown by its slug; storing the slug as the name would make a later
+        # re-run indistinguishable from somebody naming them that.
+        name = tenant.get("display_name") or ""
+        suffix = f"  {name}" if name and name != tenant["slug"] else ""
+        print(f"{tenant['slug']:<{width}}  {tenant['created_at'][:10]}{suffix}")
+    return 0

elan_cli/validate.py

@@ -0,0 +1,91 @@
+"""`elan validate` — say no here, where saying no is free.
+
+THE SAME MODEL THE SERVICE USES, imported rather than reimplemented. The point
+of validating locally is that a local yes means the service will also say yes;
+a second copy of the schema would agree until it did not, and a CLI that is
+confidently wrong is worse than one that says nothing.
+
+WHAT THIS CATCHES THAT THE SCHEMA ALONE CANNOT: the cross-check. `elan.yaml`
+and the Python MANIFESTs are in a validation relationship rather than a
+duplicated one — the manifest says what the agent asks for, the deploy file says
+what the platform will permit — and neither file can be checked against the
+other without reading both. That needs the repo's own code to run, which is why
+this command does something `POST /v1/validate` cannot do for a repo it has
+never built.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from elan_agentkit_contracts.deploy_spec import Problem, cross_check
+
+from elan_cli.manifests import ManifestError, read
+from elan_cli.project import Project, ProjectError, find
+
+
+def run(start: Path | None = None, *, python: str | None = None) -> int:
+    try:
+        project = find(start)
+    except ProjectError as exc:
+        print(f"error: {exc}")
+        return 2
+
+    print(f"{project.spec_path}")
+    print(f"  tenant   {project.spec.tenant}")
+    print(f"  project  {project.spec.project}")
+    print(f"  targets  {len(project.spec.targets)} declared")
+
+    try:
+        manifests = read(project.targets_root, python=python)
+    except ManifestError as exc:
+        print(f"\nerror: {exc}")
+        return 2
+
+    print(f"  found    {len(manifests)} in {project.targets_root}")
+
+    problems = cross_check(project.spec, manifests)
+    if not problems:
+        print("\nok — this would be accepted.")
+        _warn_unenforced(project)
+        return 0
+
+    # EVERY PROBLEM, NOT THE FIRST. A developer fixing one, pushing, and waiting
+    # for a build to report the next is how a five-minute edit becomes an
+    # afternoon. `cross_check` returns them all for the same reason.
+    print(f"\nrefused — {len(problems)} problem(s):\n")
+    for problem in problems:
+        _print(problem)
+    return 1
+
+
+def _print(problem: Problem) -> None:
+    print(f"  {problem.where}")
+    for line in problem.message.splitlines():
+        print(f"    {line}")
+    print()
+
+
+def _warn_unenforced(project: Project) -> None:
+    """`paths:` is parsed, stored, shown — and NOT enforced.
+
+    Path-level egress needs TLS interception, which means the platform could
+    read a tenant's traffic to third parties. That is a consent decision rather
+    than a config flag, so v2 enforces the HOST and says so out loud. "Declared
+    but unenforced" silently read as "enforced" is how people get breached.
+    """
+    declared = sorted({
+        rule.host
+        for slug in project.spec.targets
+        for rule in (project.spec.resolved(slug).egress or [])
+        if rule.paths
+    })
+    if not declared:
+        return
+    print()
+    print("  note: `paths:` is recorded and shown, but NOT enforced. Only the")
+    print("        HOST is. Enforcing a path needs TLS interception, which")
+    print("        would let the platform read your traffic to that host — so")
+    print("        it is not done silently. Affected:")
+    for host in declared:
+        print(f"          {host}")

elan_cli/wallet.py

@@ -0,0 +1,213 @@
+"""`elan wallet` — credit a tenant holds for THEIR OWN end users.
+
+WHY THIS EXISTS, given the console has a page for it: this is the surface a
+developer automates against. Topping up a user from a support script, seeding
+promo credit in CI, or checking a balance while debugging a refusal are all things
+somebody does from a terminal, and the alternative was `curl` with a hand-built
+bearer. A CLI that mirrors the API is also the fastest way to find out the API is
+wrong — which is exactly how the missing `eu:` join would have been caught.
+
+DOLLARS IN, MICRO-USD ON THE WIRE. A person types `5` and means five dollars; the
+ledger counts in micro-USD because a float price is a rounding argument with a
+customer. The conversion is here, in one place, and `--micros` exists for the
+caller who already has the integer and should not have to divide by a million to
+pass it back.
+
+NO `--tenant`. Every route derives the tenant from the verified token, so naming
+one would be a value the service ignores — and offering a flag that does nothing
+is worse than not offering it.
+
+THE PROJECT IS NOT OPTIONAL BUT IS USUALLY IMPLICIT. A wallet is keyed on
+`(tenant, project, external_user_id)` because a tenant runs several products and
+`ada` in one is not `ada` in another. Run inside a project and `elan.yaml` answers
+it, the way `elan deploy` already works; `--project` is for a script that is not
+standing in one.
+
+WHAT THIS DELIBERATELY CANNOT DO: close a wallet. Closing needs a zero balance and
+is the one action here that is not meant to be reversed, so it stays in the console
+where the balance is on screen beside the button. `freeze` covers the urgent case.
+"""
+
+from __future__ import annotations
+
+from elan_cli.client import Api
+from elan_cli.project import ProjectError, find
+
+#: Micro-USD in one dollar.
+MICROS = 1_000_000
+
+
+class WalletError(Exception):
+    """Phrased for the developer running the command."""
+
+
+def _base(project: str) -> str:
+    """Every wallet route, under its project. One place, so no command can drop
+    half the key."""
+    return f"/v1/projects/{project}/wallets"
+
+
+def project_of(explicit: str) -> str:
+    """The project to act in: what was asked for, or what `elan.yaml` says.
+
+    THE LOCAL FILE RATHER THAN A REMEMBERED DEFAULT. `elan deploy` resolves a
+    project the same way, so standing in a directory means the same thing to both
+    — and a remembered one would make `elan wallet credit ada 5` act on whichever
+    project was touched last, which is the shape of a mistake somebody only finds
+    in their statement.
+    """
+    if explicit.strip():
+        return explicit.strip()
+    try:
+        return find().spec.project
+    except ProjectError as exc:
+        raise WalletError(
+            "which project? run this inside one, or pass --project "
+            f"({exc})") from exc
+
+
+def _micros(dollars: str | None, micros: int | None) -> int:
+    """The amount, in micro-USD, from whichever form the caller used.
+
+    ROUNDED RATHER THAN TRUNCATED. `1.1 * 1_000_000` is 1100000.0000001 in
+    binary floating point, and `int()` on that credits a user one micro-USD less
+    than they were promised — which nobody would ever find, and which makes a
+    statement that does not add up.
+    """
+    if micros is not None:
+        return micros
+    if dollars is None:
+        raise WalletError("give an amount in dollars, or --micros")
+    try:
+        return round(float(dollars) * MICROS)
+    except ValueError as exc:
+        raise WalletError(f"{dollars!r} is not an amount in dollars") from exc
+
+
+def _money(micros: int) -> str:
+    """Micro-USD as dollars, without rounding a real charge away.
+
+    The same rule the console's `money()` follows: a charge of 1,477 micro-USD is
+    `$0.0015` and not `$0.00`, because a table of charges that reads as all zeroes
+    describes charges that were genuinely made.
+    """
+    major = micros / MICROS
+    if major == 0:
+        return "$0.00"
+    # THE SIGN GOES BEFORE THE SYMBOL. `$-2.50` is not how money is written, and a
+    # statement is mostly negatives — every run spends.
+    sign = "-" if major < 0 else ""
+    size = abs(major)
+    if size >= 0.01:
+        return f"{sign}${size:,.2f}"
+    return f"{sign}${size:.4f}"
+
+
+def ls(api: Api, project: str, limit: int = 50) -> int:
+    page = api.request("GET", f"{_base(project)}?limit={limit}")
+    wallets = page.get("wallets", [])
+    if not wallets:
+        print("no wallets yet — `elan wallet create <user>` makes one")
+        return 0
+
+    width = max(len(w["external_user_id"]) for w in wallets)
+    for wallet in wallets:
+        held = wallet.get("held_micros") or 0
+        # HELD IS SHOWN ONLY WHEN THERE IS SOME, because it explains a balance
+        # that looks wrong — a run in flight has reserved its worst case and has
+        # not been charged yet — and is noise on every other row.
+        extra = f"  ({_money(held)} held)" if held else ""
+        state = wallet.get("status", "")
+        label = f"  {wallet['display_label']}" if wallet.get("display_label") else ""
+        print(f"{wallet['external_user_id']:<{width}}  "
+              f"{_money(wallet.get('available_micros', 0)):>12}  "
+              f"{state:<7}{extra}{label}")
+
+    total = page.get("total", len(wallets))
+    if total > len(wallets):
+        print(f"\n{len(wallets)} of {total}; --limit for more")
+    return 0
+
+
+def show(api: Api, project: str, user: str) -> int:
+    wallet = api.request("GET", f"{_base(project)}/{user}")
+    print(f"user       {wallet['external_user_id']}")
+    if wallet.get("display_label"):
+        print(f"label      {wallet['display_label']}")
+    print(f"status     {wallet.get('status', '')}")
+    print(f"available  {_money(wallet.get('available_micros', 0))}")
+    if wallet.get("held_micros"):
+        print(f"held       {_money(wallet['held_micros'])}"
+              "   (reserved by a run in flight, not yet charged)")
+    print(f"balance    {_money(wallet.get('balance_micros', 0))}")
+    return 0
+
+
+def create(api: Api, project: str, user: str, label: str = "") -> int:
+    wallet = api.request("POST", _base(project),
+                         json={"external_user_id": user, "display_label": label})
+    # IDEMPOTENT, SO THIS DOES NOT CLAIM TO HAVE CREATED ANYTHING. Running it on
+    # every sign-in is the expected pattern, and "created" on the fortieth call
+    # would be a lie somebody eventually relies on.
+    print(f"{wallet['external_user_id']}  "
+          f"{_money(wallet.get('available_micros', 0))}  "
+          f"{wallet.get('status', '')}")
+    return 0
+
+
+def credit(api: Api, project: str, user: str, dollars: str | None,
+           micros: int | None, ref: str = "") -> int:
+    amount = _micros(dollars, micros)
+    if amount <= 0:
+        raise WalletError("a credit must be positive; use `adjust` to take credit away")
+    done = api.request("POST", f"{_base(project)}/{user}/credits",
+                       json={"micros": amount, "ref": ref or None})
+    print(f"credited {_money(amount)} to {user}  {done.get('transaction_id', '')}")
+    return 0
+
+
+def adjust(api: Api, project: str, user: str, dollars: str | None,
+           micros: int | None, ref: str = "") -> int:
+    amount = _micros(dollars, micros)
+    if amount == 0:
+        raise WalletError("an adjustment of zero records nothing")
+    done = api.request("POST", f"{_base(project)}/{user}/adjustments",
+                       json={"micros": amount, "ref": ref or None})
+    verb = "credited" if amount > 0 else "clawed back"
+    print(f"{verb} {_money(abs(amount))} on {user}  "
+          f"{done.get('transaction_id', '')}")
+    return 0
+
+
+def status(api: Api, project: str, user: str, state: str) -> int:
+    wallet = api.request("POST", f"{_base(project)}/{user}/status",
+                         json={"status": state})
+    if state == "frozen":
+        # SAYS WHAT THE END USER WILL SEE, because that is the question somebody
+        # freezing an account is about to be asked.
+        print(f"{user} is frozen; their balance is untouched and runs are refused "
+              "as unavailable rather than out of credit")
+    else:
+        print(f"{user} is {wallet.get('status', state)}")
+    return 0
+
+
+def statement(api: Api, project: str, user: str, limit: int = 25) -> int:
+    page = api.request("GET",
+                       f"{_base(project)}/{user}/statement?limit={limit}")
+    entries = page.get("entries", [])
+    if not entries:
+        print("nothing has moved on this wallet yet")
+        return 0
+
+    words = {"grant": "credit", "settle": "run", "adjustment": "correction"}
+    for entry in entries:
+        kind = words.get(entry.get("kind", ""), entry.get("kind", ""))
+        ref = f"  {entry['ref']}" if entry.get("ref") else ""
+        print(f"{entry.get('created_at', '')[:19]}  {kind:<11}  "
+              f"{_money(entry.get('amount_micros', 0)):>12}{ref}")
+
+    total = page.get("total", len(entries))
+    if total > len(entries):
+        print(f"\n{len(entries)} of {total}; --limit for more")
+    return 0

elan_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: elan-cli
+Version: 0.1.0
+Summary: The command line a developer deploys an agent with
+Project-URL: Homepage, https://openelan.ai
+Project-URL: Documentation, https://openelan.ai/app/docs
+Author-email: Elan <support@openelan.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: adk,agents,cli,deployment,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: certifi>=2024.2.2
+Requires-Dist: elan-agentkit-contracts
+Requires-Dist: elan-sdk
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: websockets>=13.0
+Description-Content-Type: text/markdown
+
+# elan-cli
+
+The command line a developer deploys an agent with. Installs the `elan`
+command.
+
+```bash
+uv tool install elan-cli        # or: pipx install elan-cli
+```
+
+Requires Python 3.12 or newer.
+
+## Getting started
+
+```bash
+elan login                      # device-code sign-in against the platform
+elan init --tenant acme --project agents
+elan env                        # build the project's venv
+elan validate                   # say no here, where saying no is free
+elan deploy
+elan invoke invoice-triage --text "What do I owe on INV-9?"
+```
+
+`elan login` reaches the production API by default. Point it elsewhere with
+`elan login --api https://…`, or set `ELAN_API`.
+
+## What it covers
+
+| Group | Commands |
+|---|---|
+| Signing in | `login`, `logout`, `whoami` |
+| Project setup | `init`, `new {agent,workflow}`, `projects {ls,create}` |
+| Local development | `env`, `adk`, `validate` |
+| Shipping | `deploy`, `status`, `logs`, `rollback` |
+| Operating | `agents`, `invoke`, `doctor`, `destroy` |
+| Secrets | `secret {set,ls,rm}` |
+| Files | `files {ls,get,put,rm}` |
+| Wallets | `wallet {ls,show,create,credit,adjust,freeze,unfreeze,statement}` |
+
+`elan <command> --help` for the flags.
+
+## Where it keeps things
+
+Configuration is a plain JSON file at `~/.config/elan/config.json`, mode
+`0600`, holding only public values — the API URL, the issuer, the client id.
+Override the directory with `ELAN_HOME`, or the API with `ELAN_API`.
+
+**Credentials never go in a file.** The refresh token is stored in the OS
+keyring under the service name `elan-cli`. The CLI will not fall back to
+writing one to disk; if `keyring` cannot be reached it says so and stops.
+
+Per-project state lives in `.elan/` beside your `elan.yaml`, and is
+git-ignored.
+
+## Exit codes
+
+| | |
+|---|---|
+| `0` | it worked |
+| `1` | it ran, and the answer was no — a refused deploy, a failed validation |
+| `2` | it could not run — no project, no credential, no network |
+
+Errors print as `error: …` on stderr with no traceback.
+
+## Documentation
+
+The full command reference and the platform guides are at
+<https://openelan.ai/app/docs>.
+
+## Licence
+
+Apache-2.0. See `LICENSE`.

elan_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+elan_cli/__init__.py,sha256=oTkVmV-vxUHF0Ew_TZXeUj4WhIZSc5FmrZUaBzIBgXY,220
+elan_cli/adk.py,sha256=Wim59nEppwGWRTzXIvDWATUivByiphiIAuhhktXur5o,8144
+elan_cli/auth.py,sha256=a9v2mQZGKzHPiWRz-HL8jSVN1oPcJUAfDTU8lxQvvSk,15614
+elan_cli/client.py,sha256=Br-YdThu816lSwoIpYklb3hujv47lNARSXveym_1FmI,4862
+elan_cli/config.py,sha256=RqSOFh_TK_5Bi6AqOQZPada90FAtS7gclJvOn_tBlkI,6109
+elan_cli/deploy.py,sha256=UTe7SIQkMMP5eudRDwup6t3GnaRKtzKAJfxEuDzSCMk,9751
+elan_cli/destroy.py,sha256=zQlb0pkFiD79bwq3TX5JSgkNS9sc14nRLBDaJrgcKYE,3180
+elan_cli/doctor.py,sha256=zXB-CC7tCNQlX8ktkgD5ghGLwjcgQ-QhbgF1L_O6fGk,2535
+elan_cli/env.py,sha256=53mNrnm7RrG3Q7tgWt0ARTMoa58xZ8i1n0i621nbOJE,4008
+elan_cli/files.py,sha256=AIv3i-6yNhQ_1sgoMdgq1Lv0ecPQirUKM3OXCXLEkNk,6302
+elan_cli/invoke.py,sha256=SsaHWrWRJoirfkKsvkqoZX-aiJjTYIFsq1jyiS4l_6Q,9394
+elan_cli/logs.py,sha256=qpiqnipK8MgeTishyOWzJx7hs53ZmwstivCFEyx-9ws,6171
+elan_cli/main.py,sha256=67ZBBWBggvK1vwf5GcZ4qTxt_hyExXtCnN_QYLmMawY,29499
+elan_cli/manifests.py,sha256=lziJcrVn0qib70rpbSf-Lm0HSF_kUI0HgeMQluszOlw,5786
+elan_cli/project.py,sha256=v7Vp4dw7JWesf70K2fJ0bMJwEJMqsLqtPWP1z0N-TFk,5662
+elan_cli/projects.py,sha256=EeWdJ5BBE0sncOSgbZMxEZug8l5hpUu46EmAOpONOWw,2656
+elan_cli/rollback.py,sha256=-wjAU6ZM4vDg_Rd3uHbrswShHW6ZZkVXCPxlZm4t7ho,2740
+elan_cli/scaffold.py,sha256=6dEwaCTMg7riyydpFzEADsGIa6hjKhaOSBTpac9Ql2I,17094
+elan_cli/secret.py,sha256=Y3sp866TPRsBzE2Iu4Ncw1mAQk3TtEv1FHEdmHPN7t8,4311
+elan_cli/stream.py,sha256=ESvMHNivLUS3Q_Mzrm1TjCk9fXFcfXNm30PizamhKP4,7589
+elan_cli/tenant.py,sha256=HjYvxyXlAwyGBClzPyH7nAQrGYHWCY1WLV3HXNV0Ta8,2697
+elan_cli/validate.py,sha256=R3HIm5CFasHBprcc85XCCaFwN4oXuG4lWOoHu1ry8Rg,3383
+elan_cli/wallet.py,sha256=YVXoqtO1IaLaubPccf_0TrV4rmNnIDZmx1c-Py-DrVw,9032
+elan_cli-0.1.0.dist-info/METADATA,sha256=6fvz2T4RtX-E3X6cPjbHfzJWrNH03osoSBALVhL9xxQ,3066
+elan_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+elan_cli-0.1.0.dist-info/entry_points.txt,sha256=nhqf7kifhbxc2pEurRsqWIr_GgA2FwfQQViKfw5fUUs,43
+elan_cli-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+elan_cli-0.1.0.dist-info/RECORD,,

elan_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

elan_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+elan = elan_cli.main:run