elan-cli 0.1.0__py3-none-any.whl

elan_cli/manifests.py

@@ -0,0 +1,124 @@
+"""Reading a repo's manifests on the developer's own machine.
+
+THIS IS THE ONE PLACE CUSTOMER CODE IS IMPORTED BY CHOICE, and where it belongs:
+the customer's own laptop, running their own code, at their own request. The
+deploy service never does this — it reads `manifests.json` produced inside the
+build sandbox, because a manifest is the result of EXECUTING a module and the
+trust boundary there has to be a process rather than a parser.
+
+The asymmetry is the design. Here there is no boundary to cross: a developer
+running `elan validate` on their own repo is already running their own code
+every time they run their own tests.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+class ManifestError(Exception):
+    """The repo's targets could not be read, with the reason the developer needs."""
+
+
+class NoRuntime(ManifestError):
+    """The chosen interpreter does not have the platform runtime in it.
+
+    A SEPARATE TYPE BECAUSE IT IS A SEPARATE PROBLEM, and for a while it wore
+    the other one's message: "this runs your own code, so the error above is
+    from your repo". It is not from their repo. Nothing they can write in an
+    agent module fixes a missing `agentkit_runtime`, so that sentence sent
+    somebody reading it to look at the one place the answer is not.
+    """
+
+
+def interpreter(root: Path, override: str | None = None) -> tuple[str, str]:
+    """Which Python runs the exporter, and WHY — the reason goes in the error.
+
+    THE CLI'S OWN INTERPRETER IS THE LAST RESORT, not the first. `elan` is
+    installed as a tool, which on purpose puts it in an isolated environment
+    containing the CLI and nothing else — so `sys.executable` is the one
+    interpreter guaranteed NOT to have the repo's dependencies in it. Reaching
+    for it first is what made a missing environment look like broken code.
+
+    AN UNACTIVATED `.venv` STILL COUNTS. `uv venv` creates one without
+    activating it, and a developer who has just run it and not sourced
+    anything is in the commonest state there is.
+    """
+    if override:
+        return override, "--python"
+    active = os.environ.get("VIRTUAL_ENV")
+    if active:
+        return str(Path(active) / "bin" / "python"), "$VIRTUAL_ENV"
+    local = root / ".venv" / "bin" / "python"
+    if local.exists():
+        return str(local), f"{local.parent.parent}"
+    return sys.executable, "the elan CLI's own environment"
+
+
+def read(targets_root: Path, *, python: str | None = None) -> list[dict]:
+    """Every target's manifest, by running the repo's own exporter.
+
+    A SUBPROCESS, NOT AN IMPORT INTO THIS PROCESS, and that is worth the cost.
+    Importing a tenant's package here would put their `sys.modules`, their
+    monkeypatches and their import-time side effects inside the CLI for the rest
+    of its life — so `elan new agent` after `elan validate` would run in an
+    interpreter the repo had already modified. It also means a module that
+    raises on import produces a traceback the developer can read, rather than
+    taking the CLI down with it.
+
+    THE SAME ENTRYPOINT THE BUILD USES. `python -m agentkit_runtime.manifest_export`
+    runs in the build sandbox too, so what the developer validates against is
+    what the deploy service will later be handed — not a second implementation
+    that agrees with it today.
+    """
+    chosen, why = interpreter(targets_root, python)
+    out = subprocess.run(
+        # `--root`, and no `--out`: the exporter writes JSON to stdout and its
+        # diagnostics to stderr, so the two never need separating here.
+        [chosen, "-m", "agentkit_runtime.manifest_export",
+         "--root", str(targets_root)],
+        capture_output=True, text=True, cwd=targets_root,
+    )
+    if out.returncode != 0:
+        detail = out.stderr.strip() or out.stdout.strip()
+        # TOLD APART BY THE MODULE THAT IS MISSING. `agentkit_runtime` is the
+        # exporter itself, so its absence means the environment, and anything
+        # else means the repo.
+        if "No module named 'agentkit_runtime'" in detail:
+            raise NoRuntime(
+                "this repo has no environment to read its agents with.\n\n"
+                f"Tried:  {chosen}\n"
+                f"        ({why})\n\n"
+                "Checking elan.yaml against your MANIFESTs means IMPORTING\n"
+                "your agents, which needs the platform runtime and whatever\n"
+                "else they import. The elan CLI deliberately does not carry\n"
+                "those — it would drag a web server and a database driver\n"
+                "onto your machine for a command that only reads files.\n\n"
+                "Everything above this line was checked and is fine. What was\n"
+                "skipped is the cross-check between the two files.\n\n"
+                "Create one:\n"
+                "  elan env\n\n"
+                "It makes a `.venv` beside elan.yaml, which is then found\n"
+                "without being named. `--python` points at one elsewhere."
+            )
+        raise ManifestError(
+            "could not read this repo's targets.\n\n"
+            f"{detail}\n\n"
+            f"Read with {chosen}\n"
+            f"({why})\n\n"
+            "That interpreter has the runtime, so this is from your repo —\n"
+            "a module that raises on import, a missing MANIFEST, or two\n"
+            "targets declaring the same slug. The build would fail the same\n"
+            "way, which is why this check exists here."
+        )
+    try:
+        return json.loads(out.stdout)
+    except ValueError as exc:
+        raise ManifestError(
+            f"the exporter did not produce JSON: {exc}. "
+            f"First 200 characters: {out.stdout[:200]!r}"
+        ) from exc

elan_cli/project.py

@@ -0,0 +1,137 @@
+"""Finding a tenant's repo, and editing its deploy file without losing anything.
+
+TWO FILES THAT MUST NOT DRIFT. `elan.yaml` declares what the platform will
+provision; each target's Python MANIFEST declares what it does. A target present
+in one and absent from the other is refused at deploy time in BOTH directions —
+so a scaffolding command that writes the module and leaves the developer to
+remember the YAML has built the failure it was meant to prevent.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from elan_agentkit_contracts.deploy_spec import DeploySpec, spec_from_yaml
+
+#: The deploy file's name is fixed, and deliberately not configurable. A flag
+#: for it would mean two repos could disagree about where their own contract
+#: lives, and every error message would have to name the file it happened to be
+#: reading.
+SPEC_FILENAME = "elan.yaml"
+
+
+class ProjectError(Exception):
+    """Something about the repo's shape, phrased for whoever has to fix it."""
+
+
+@dataclass(frozen=True, slots=True)
+class Project:
+    """A tenant's repo as the CLI needs it."""
+
+    #: Where `elan.yaml` is. Every path the CLI prints is relative to this, so a
+    #: developer can paste one into an editor without adjusting it.
+    root: Path
+    spec_path: Path
+    spec: DeploySpec
+
+    @property
+    def targets_root(self) -> Path:
+        """Where `agents/` and `workflows/` live.
+
+        RELATIVE TO elan.yaml, NOT TO THE WORKING DIRECTORY. `targetsRoot` is
+        read by the build too, which runs with the repo root as its cwd — so
+        resolving it against wherever the developer happened to type the command
+        would make `elan validate` and the build disagree about which files
+        exist.
+        """
+        return (self.root / self.spec.source.targets_root).resolve()
+
+
+def find(start: Path | None = None) -> Project:
+    """The nearest enclosing repo, searched upward from `start`.
+
+    UPWARD, like git. A developer editing `agents/invoice/agent.py` should be
+    able to run `elan validate` there without first working out how many
+    directories up the deploy file is — and being told "no elan.yaml here" while
+    standing inside the repo is the kind of small friction that makes a tool feel
+    hostile.
+    """
+    here = (start or Path.cwd()).resolve()
+    for directory in [here, *here.parents]:
+        candidate = directory / SPEC_FILENAME
+        if candidate.is_file():
+            return load(candidate)
+    raise ProjectError(
+        f"no {SPEC_FILENAME} in {here} or any directory above it.\n"
+        f"  `elan init` creates one, or run this from inside a project."
+    )
+
+
+def load(spec_path: Path) -> Project:
+    try:
+        text = spec_path.read_text()
+    except OSError as exc:
+        raise ProjectError(f"cannot read {spec_path}: {exc}") from exc
+    try:
+        spec = spec_from_yaml(text)
+    except Exception as exc:
+        # THE SCHEMA'S OWN MESSAGE, NOT A SUMMARY OF IT. Pydantic names the
+        # field and the rule it broke; rewording that here would lose the field
+        # path, which is the only part that says where to look.
+        raise ProjectError(f"{spec_path}:\n{exc}") from exc
+    return Project(root=spec_path.parent.resolve(), spec_path=spec_path, spec=spec)
+
+
+def add_target(spec_path: Path, slug: str) -> None:
+    """Append a `targets:` entry, preserving everything already in the file.
+
+    A TEXT EDIT, NOT A PARSE-AND-DUMP, and the reason is the file itself. This
+    one is dense with comments explaining why each block says what it says —
+    `yaml.safe_dump` would silently delete every one of them, reorder the keys,
+    and hand the developer back a diff touching a file they did not edit. A
+    scaffolding command that does that is one nobody runs twice.
+
+    So the entry is inserted as text, under the existing `targets:` key, and the
+    surrounding bytes are untouched.
+    """
+    text = spec_path.read_text()
+    lines = text.splitlines(keepends=True)
+
+    # TWO FORMS, BECAUSE `elan init` HAS TO WRITE THE SECOND. A bare `targets:`
+    # with nothing under it is YAML `None`, not an empty mapping, so a freshly
+    # scaffolded file would not parse at all — it is written as `targets: {}`
+    # and collapsed back to a plain key here the first time something is added.
+    index = next((i for i, line in enumerate(lines)
+                  if line.rstrip() in ("targets:", "targets: {}")), None)
+    if index is None:
+        raise ProjectError(
+            f"{spec_path} has no top-level `targets:` key to add to. "
+            "Add one and re-run, or declare the target by hand."
+        )
+    if lines[index].rstrip() == "targets: {}":
+        lines[index] = "targets:\n"
+
+    entry = (
+        f"\n  {slug}:\n"
+        f"    # Takes every value from `defaults:` above. Override any block\n"
+        f"    # here — a block replaces the default entirely rather than\n"
+        f"    # merging field by field, so state all of it or none of it.\n"
+        f"    database: {{enabled: true}}\n"
+    )
+
+    # AFTER THE LAST TARGET, NOT IMMEDIATELY AFTER THE KEY. Inserting at the top
+    # would put the new entry above targets that were there first, so every
+    # `elan new` would reorder somebody else's file and the diff would show
+    # changes nobody made.
+    end = len(lines)
+    for i in range(index + 1, len(lines)):
+        stripped = lines[i]
+        if stripped.strip() and not stripped.startswith((" ", "\t")):
+            end = i
+            break
+    while end > index + 1 and not lines[end - 1].strip():
+        end -= 1
+
+    lines.insert(end, entry)
+    spec_path.write_text("".join(lines))

elan_cli/projects.py

@@ -0,0 +1,72 @@
+"""`elan projects` and `elan agents` — what exists, and what it is running.
+
+READ FROM THE SERVICE, NOT FROM elan.yaml. The file says what this checkout
+intends; these say what the platform actually has. Those differ whenever
+somebody else deployed, or a deploy half-failed, which is exactly when
+somebody runs them.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from elan_cli.client import Api, ApiError
+
+
+def ls(api: Api) -> int:
+    try:
+        rows = api.request("GET", "/v1/projects").get("projects", [])
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+    if not rows:
+        print("No projects yet. `elan projects create <name>`.")
+        return 0
+
+    print(f"{'PROJECT':<18} {'AGENTS':>6} {'DEPLOYS':>7}  {'LAST':<10} REPOSITORY")
+    for row in rows:
+        # A PROJECT NOBODY CREATED still appears — it exists because something
+        # was deployed to it — and says so rather than showing blanks that
+        # read as missing data.
+        repo = row.get("repo_url") or ("from deploy history"
+                                       if not row.get("registered") else "-")
+        print(f"{row['slug']:<18} {row.get('agents', 0):>6} "
+              f"{row.get('deployments', 0):>7}  "
+              f"{(row.get('last_state') or '-'):<10} {repo}")
+    return 0
+
+
+def create(api: Api, slug: str, name: str, repo: str) -> int:
+    try:
+        api.request("POST", "/v1/projects",
+                    json={"slug": slug, "display_name": name,
+                          "repo_url": repo})
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+    print(f"Created {slug}.")
+    print(f"  elan init --tenant <you> --project {slug}")
+    return 0
+
+
+def agents(api: Api, project: str) -> int:
+    path = "/v1/agents" + (f"?project={project}" if project else "")
+    try:
+        rows = api.request("GET", path).get("agents", [])
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+    if not rows:
+        print("Nothing deployed." if project
+              else "Nothing deployed in any project.")
+        return 0
+
+    print(f"{'AGENT':<24} {'PROJECT':<16} {'VERSION':<10} DIGEST")
+    for row in rows:
+        # EACH AGENT'S OWN DIGEST. Targets share an image lineage and move
+        # independently, so a single "current version" for a project would be
+        # a lie whenever a deploy moved some and not others.
+        digest = str(row.get("digest", "")).rsplit("@", 1)[-1][:19] or "-"
+        print(f"{row['slug']:<24} {row.get('project', ''):<16} "
+              f"{(row.get('version') or '-'):<10} {digest}")
+    return 0

elan_cli/rollback.py

@@ -0,0 +1,68 @@
+"""`elan rollback` — put a project back the way a previous deploy left it.
+
+NO REBUILD. The images it moves back to already exist, were already scanned
+and are already attested, which is what makes this fast enough to reach for
+during an incident. Rebuilding the same source would produce a DIFFERENT
+digest — timestamps, base-image drift — so it would be a new deploy wearing
+old code, and Binary Authorization would have to attest it first.
+
+IT ASKS BEFORE IT ACTS, unless told not to. A rollback is not destructive in
+the way `destroy` is, but it does move every target at once and without the
+canary staging a deploy gets — so the confirmation prints what will change and
+names the deployment being restored.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from elan_cli.client import Api, ApiError
+from elan_cli.deploy import _watch
+from elan_cli.project import find
+
+
+def run(api: Api, to: str, *, wait: bool = True, assume_yes: bool = False) -> int:
+    """Roll `project` back to deployment `to`."""
+    project = find()
+
+    # WHAT IT IS GOING BACK TO, FETCHED FIRST. A rollback names a deployment
+    # id, which is opaque — printing the date and what it ran is the
+    # difference between confirming a decision and confirming a string.
+    try:
+        target = api.request("GET", f"/v1/deployments/{to}")
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+
+    rollout = target.get("rollout") or {}
+    print(f"Rolling {project.spec.project} back to {to}")
+    print(f"  started   {target.get('started_at', 'unknown')}")
+    print(f"  state     {target.get('state', 'unknown')}")
+    print(f"  targets   {len(rollout)}")
+    for slug, digest in sorted(rollout.items()):
+        print(f"    {slug:<24} {digest.split('@')[-1][:19]}")
+
+    if not assume_yes:
+        # NOT A y/N PROMPT ON A NAME NOBODY TYPED. The project is read from
+        # elan.yaml and the deployment id was given as an argument, so the
+        # confirmation is about the CONSEQUENCE, not about spelling.
+        print("\nEvery target above moves at once — a rollback is not staged "
+              "the way a deploy is.")
+        if input("Continue? [y/N] ").strip().lower() not in {"y", "yes"}:
+            print("Nothing was changed.")
+            return 1
+
+    try:
+        started = api.request(
+            "POST", f"/v1/projects/{project.spec.project}/rollback",
+            json={"to_deployment_id": to})
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+
+    deployment_id = started["deployment_id"]
+    print(f"\nrollback {deployment_id}")
+    if not wait:
+        print(f"  elan status {deployment_id}")
+        return 0
+    return _watch(api, deployment_id)