mkctl 0.4.0__py3-none-any.whl

mkctl/commands.py

@@ -0,0 +1,527 @@
+"""What each command does, once there is a login to do it with.
+
+`C14`. Every function here is one or two calls against endpoints that already existed:
+this is the CLI catching up with the API, not new platform behaviour. Where a command
+looks like it is doing something clever it is doing the opposite — resolving a name the
+caller knows into an id the API wants, and nothing else.
+
+Two decisions worth stating, because both could reasonably have gone the other way.
+
+**A bundle is pushed, not built.** `mkbundle build` produces the archive and this uploads
+it. Building needs a connector catalog, `mklang check` on every machine, and a signing
+key; folding that in would make one command that fails for eight unrelated reasons and
+would put a signing key in the same process as a login token.
+
+**Inputs are strings unless the caller says otherwise.** `--input thread_id=t-1` sends a
+string, and `--input-json` is how anything else is expressed. A shell word carries no
+type, so guessing one — `count=2` as a number here and a string somewhere else — would
+make the same command mean two things depending on what the value looked like.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from mkp_contracts.archive import manifest_of
+from mkp_contracts.errors import ContractError
+
+from .client import ControlPlane, ControlPlaneError
+
+DASH = "-"
+
+
+def _scope_of(binding: dict) -> str:
+    """Where a binding applies, as one readable phrase."""
+    if binding.get("environment"):
+        return f"{binding['project']}/{binding['environment']}"
+    if binding.get("project"):
+        return f"project {binding['project']}"
+    return "the whole tenant"
+
+
+# ---------------------------------------------------------------------------
+# Who am I.
+# ---------------------------------------------------------------------------
+
+
+def whoami(plane: ControlPlane, args: argparse.Namespace) -> int:
+    body = plane.get("/v1/me")
+    if not _as_json(args, body):
+        print(f"principal  {body['principal_id']} ({body['kind']})")
+        print(f"tenant     {body['tenant_id']}")
+        # `roles` would print the same line for a role over the whole tenant and a role
+        # over one project, and the second one is refused by every tenant-scoped endpoint
+        # (`D14`). One line per binding, with where it applies.
+        for binding in body.get("bindings") or []:
+            print(f"role       {binding['role']} on {_scope_of(binding)}")
+    if not body.get("roles"):
+        # Being authenticated is not being authorized, and a user with no binding can
+        # do nothing at all. Saying so here saves a confusing round of 403s.
+        _warn("no role binding: you are authenticated but not authorized for anything yet")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Bundles and the pointer.
+# ---------------------------------------------------------------------------
+
+
+def bundle_push(plane: ControlPlane, args: argparse.Namespace) -> int:
+    """Register the manifest, then upload the bytes.
+
+    Two calls because they are two facts (`routes.py`), and in this order because the
+    upload is refused for a bundle nobody registered. The digest is the server's answer
+    to the first call — see `client.py` for why this does not compute its own.
+    """
+    archive = Path(args.archive)
+    payload = archive.read_bytes()
+    try:
+        manifest = manifest_of(payload)
+    except (ContractError, KeyError, ValueError) as exc:
+        raise ControlPlaneError(0, f"{archive}: not a bundle archive — {exc}") from exc
+
+    registered = plane.post(f"/v1/projects/{args.project}/bundles", json={"manifest": manifest})
+    digest = registered["digest"]
+    plane.put(f"/v1/projects/{args.project}/bundles/{digest}/archive", content=payload)
+
+    if not _as_json(args, {"digest": digest, "project": args.project, "bytes": len(payload)}):
+        print(f"registered  {digest}")
+        print(f"uploaded    {_size(len(payload))}")
+        signature = manifest.get("signature")
+        # Not an error here: the control plane accepts an unsigned bundle and the runner
+        # refuses one (`D2`). Saying so at push time is the difference between finding out
+        # now and finding out one poll later, on a runner, as a run that will not start.
+        if not signature:
+            _warn("this bundle is unsigned, and a runner refuses what it cannot verify (D2)")
+    return 0
+
+
+def deploy(plane: ControlPlane, args: argparse.Namespace) -> int:
+    body = plane.post(
+        f"/v1/projects/{args.project}/environments/{args.environment}/deployments",
+        json={"bundle_digest": args.digest},
+    )
+    if not _as_json(args, body):
+        print(f"deployed {_short(args.digest)} to {args.project}/{args.environment}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Projects and environments.
+# ---------------------------------------------------------------------------
+
+
+def project_list(plane: ControlPlane, args: argparse.Namespace) -> int:
+    rows = plane.get("/v1/projects")
+    if not _as_json(args, rows):
+        _table(["PROJECT", "ID"], [[row["slug"], row["id"]] for row in rows])
+    return 0
+
+
+def project_create(plane: ControlPlane, args: argparse.Namespace) -> int:
+    body = plane.post("/v1/projects", json={"slug": args.slug})
+    if not _as_json(args, body):
+        print(f"created project {body['slug']}")
+    return 0
+
+
+def environment_list(plane: ControlPlane, args: argparse.Namespace) -> int:
+    rows = plane.get(f"/v1/projects/{args.project}/environments")
+    if not _as_json(args, rows):
+        _table(
+            ["ENVIRONMENT", "DEPLOYED"],
+            [[row["name"], _short(row["bundle_digest"])] for row in rows],
+        )
+    return 0
+
+
+def environment_create(plane: ControlPlane, args: argparse.Namespace) -> int:
+    body = plane.post(f"/v1/projects/{args.project}/environments", json={"name": args.name})
+    if not _as_json(args, body):
+        print(f"created environment {args.project}/{body['name']}, pointing at nothing")
+    return 0
+
+
+def environment_get(plane: ControlPlane, args: argparse.Namespace) -> int:
+    body = plane.get(f"/v1/projects/{args.project}/environments/{args.name}")
+    if not _as_json(args, body):
+        print(f"environment  {args.project}/{body['environment']}")
+        print(f"bundle       {body['bundle_digest'] or DASH}")
+        print(f"config       {body['config_digest'] or DASH}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Runs, including the one that is waiting.
+# ---------------------------------------------------------------------------
+
+
+def run_start(plane: ControlPlane, args: argparse.Namespace) -> int:
+    inputs = _inputs(args)
+    body = plane.post(
+        f"/v1/projects/{args.project}/environments/{args.environment}/runs",
+        json={"workflow": args.workflow, "inputs": inputs},
+    )
+    if not _as_json(args, body):
+        print(f"run       {body['id']}")
+        print(f"workflow  {body['workflow']} on {_short(body['bundle_digest'])}")
+        print(f"status    {body['status']}")
+        # Nothing executes in that request (ADR 0002), and a person who has just been
+        # handed a run id will otherwise read `pending` as a failure to start.
+        print("\nNothing runs in this request: a runner picks it up on its next poll.")
+        # `D16`: the API says at creation when that poll is never coming.
+        for warning in body.get("warnings", []):
+            print(f"warning: {warning}", file=sys.stderr)
+    return 0
+
+
+def run_get(plane: ControlPlane, args: argparse.Namespace) -> int:
+    body = plane.get(f"/v1/runs/{args.run_id}")
+    if not _as_json(args, body):
+        print(f"run       {body['id']}")
+        print(f"workflow  {body['workflow']}")
+        if body.get("project") and body.get("environment"):
+            print(f"where     {body['project']}/{body['environment']}")
+        print(f"status    {body['status']}")
+        if body.get("error"):
+            print(f"error     {body['error']}")
+        waiting = body.get("waiting_for")
+        if waiting:
+            summary = waiting.get("summary") or f"step {waiting['step_id']}"
+            print(f"waiting   {summary} since {waiting['since']}")
+            pending = body.get("pending_reply")
+            if pending and pending.get("kind") == "abandon":
+                print("pending   abandon (runner not yet cancelled the durable run)")
+            elif pending:
+                print(f"pending   reply at {pending['step_id']} (runner not yet delivered)")
+            else:
+                print(f"\nAnswer:  mkctl run reply {body['id']} --text '…'")
+                print(f"Abandon: mkctl run abandon {body['id']}")
+        if body["steps"]:
+            print()
+            _table(
+                ["STEP", "TRY", "STATUS", "ERROR"],
+                [
+                    [
+                        step["step_id"],
+                        str(step["attempt"]),
+                        step["status"],
+                        step["error_code"] or DASH,
+                    ]
+                    for step in body["steps"]
+                ],
+            )
+    return 0
+
+
+def run_list(plane: ControlPlane, args: argparse.Namespace) -> int:
+    """Cursor-paginated runs (`GET /v1/runs`, C25)."""
+    params: dict[str, str] = {}
+    if args.status:
+        params["status"] = args.status
+    if args.project:
+        params["project"] = args.project
+    if args.environment:
+        params["environment"] = args.environment
+    if args.workflow:
+        params["workflow"] = args.workflow
+    if args.limit is not None:
+        params["limit"] = str(args.limit)
+    if args.cursor:
+        params["cursor"] = args.cursor
+    query = "&".join(f"{k}={v}" for k, v in params.items())
+    path = f"/v1/runs?{query}" if query else "/v1/runs"
+    body = plane.get(path)
+    if not _as_json(args, body):
+        items = body.get("items") or []
+        _table(
+            ["ID", "STATUS", "WORKFLOW", "WHERE", "WAITING"],
+            [
+                [
+                    row["id"],
+                    row["status"],
+                    row["workflow"],
+                    f"{row.get('project') or '?'}/{row.get('environment') or '?'}",
+                    (row.get("waiting_for") or {}).get("summary")
+                    or (row.get("waiting_for") or {}).get("step_id")
+                    or DASH,
+                ]
+                for row in items
+            ],
+        )
+        if body.get("next_cursor"):
+            print(f"\nnext page: mkctl run list --cursor {body['next_cursor']}")
+    return 0
+
+
+def run_reply(plane: ControlPlane, args: argparse.Namespace) -> int:
+    """Answer a waiting run.
+
+    `--text` covers what an escalation actually asks for — a sentence a machine reads as
+    prose — and `--json-payload` is there because the gate's answer is whatever the
+    workflow reads, not necessarily a string.
+    """
+    payload: Any = args.text
+    if args.json_payload is not None:
+        try:
+            payload = json.loads(args.json_payload)
+        except json.JSONDecodeError as exc:
+            raise ControlPlaneError(0, f"--json-payload is not JSON: {exc}") from exc
+    request: dict[str, Any] = {"payload": payload}
+    if args.step is not None:
+        request["step_id"] = args.step
+
+    body = plane.post(f"/v1/runs/{args.run_id}/reply", json=request)
+    if not _as_json(args, body):
+        print(f"answered {body['run_id']} at step {body['step_id']}")
+        # The reply is a row and the control plane holds no runner address (ADR 0002),
+        # so "answered" is not "the durable run woke" and saying otherwise would be a
+        # lie a person would then wait on.
+        print("The runner collects it on its next poll.")
+    return 0
+
+
+def run_abandon(plane: ControlPlane, args: argparse.Namespace) -> int:
+    """Abandon a waiting run (`POST /v1/runs/{id}/abandon`, C28)."""
+    request: dict[str, Any] = {}
+    if args.reason:
+        request["reason"] = args.reason
+    body = plane.post(
+        f"/v1/runs/{args.run_id}/abandon",
+        json=request if request else {},
+    )
+    if not _as_json(args, body):
+        print(f"abandon queued for {body['run_id']} at step {body['step_id']}")
+        print("The runner cancels the durable workflow on its next poll.")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Who is in a tenant, and what they may do.
+# ---------------------------------------------------------------------------
+
+
+def user_list(plane: ControlPlane, args: argparse.Namespace) -> int:
+    rows = plane.get("/v1/users")
+    if not _as_json(args, rows):
+        _table(
+            ["EMAIL", "SUBJECT", "STATUS", "ROLES"],
+            [
+                [
+                    row["email"],
+                    row["external_subject"],
+                    row["status"],
+                    # Role *and* scope: "who can deploy" is the question this table is
+                    # read for, and `maintainer` alone does not answer it (`D14`).
+                    "; ".join(
+                        f"{binding['role']} on {_scope_of(binding)}"
+                        for binding in row.get("bindings") or []
+                    )
+                    or DASH,
+                ]
+                for row in rows
+            ],
+        )
+    return 0
+
+
+def user_create(plane: ControlPlane, args: argparse.Namespace) -> int:
+    body = plane.post("/v1/users", json={"external_subject": args.subject, "email": args.email})
+    if not _as_json(args, body):
+        print(f"created user {body['email']} ({body['id']})")
+        # Membership and permission are two decisions in the API (`routes_resources.py`),
+        # and a user created here can do nothing until the second one is made.
+        print("No roles yet: grant one with `mkctl role grant`.")
+    return 0
+
+
+def role_grant(plane: ControlPlane, args: argparse.Namespace) -> int:
+    user_id = _resolve_user(plane, args.user)
+    body: dict[str, Any] = {"role": args.role}
+    if args.project is not None:
+        body["project"] = args.project
+    if args.environment is not None:
+        body["environment"] = args.environment
+    plane.put(f"/v1/users/{user_id}/roles", json=body)
+    if not _as_json(args, {"user_id": user_id, **body}):
+        print(f"granted {args.role} to {args.user} at {_scope(args)}")
+    return 0
+
+
+def role_revoke(plane: ControlPlane, args: argparse.Namespace) -> int:
+    user_id = _resolve_user(plane, args.user)
+    params = {
+        name: value
+        for name, value in (("project", args.project), ("environment", args.environment))
+        if value is not None
+    }
+    plane.delete(f"/v1/users/{user_id}/roles/{args.role}", params=params or None)
+    if not _as_json(args, {"user_id": user_id, "role": args.role, **params}):
+        print(f"revoked {args.role} from {args.user} at {_scope(args)}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Tenants, which is the one thing that acts above a tenant.
+# ---------------------------------------------------------------------------
+
+
+def tenant_list(plane: ControlPlane, args: argparse.Namespace) -> int:
+    rows = plane.get("/v1/tenants")
+    if not _as_json(args, rows):
+        _table(
+            ["TENANT", "STATUS", "CREATED"],
+            [[row["slug"], row["status"], row["created_at"][:10]] for row in rows],
+        )
+    return 0
+
+
+def tenant_create(plane: ControlPlane, args: argparse.Namespace) -> int:
+    """Create a tenant and its first owner.
+
+    Needs the platform grant, which is not a role: `mkdb grant-platform-admin` writes it
+    and `deploy/runbooks/onboarding.md` is the procedure. An operator who owns everything
+    inside a tenant still gets a 403 here, which is the point of the separation.
+    """
+    payload: dict = {
+        "slug": args.slug,
+        "owner": {"external_subject": args.owner_subject, "email": args.owner_email},
+    }
+    if args.monthly_run_limit is not None:
+        payload["monthly_run_limit"] = args.monthly_run_limit
+    if args.monthly_token_limit is not None:
+        payload["monthly_token_limit"] = args.monthly_token_limit
+    body = plane.post("/v1/tenants", json=payload)
+    if not _as_json(args, body):
+        owner = body["owner"]
+        print(f"created tenant {body['slug']} ({body['id']})")
+        print(f"owner          {owner['email']} — {', '.join(owner['roles'])}")
+    return 0
+
+
+def connection_list(plane: ControlPlane, args: argparse.Namespace) -> int:
+    rows = plane.get("/v1/connections")
+    if not _as_json(args, rows):
+        _table(
+            ["LABEL", "CONNECTOR", "STATUS"],
+            [[row["label"], row["connector"], row["status"]] for row in rows],
+        )
+    return 0
+
+
+def connection_create(plane: ControlPlane, args: argparse.Namespace) -> int:
+    """Store a static credential, or an authless row (`D10`) when material is omitted.
+
+    Material is always a map of strings from `--material name=value`. No pairs means
+    empty material — the honest shape for `auth: none` connectors that still need a
+    bound name for deploy rules.
+    """
+    material: dict[str, str] = {}
+    for pair in args.material or []:
+        name, separator, value = pair.partition("=")
+        if not separator:
+            raise ControlPlaneError(400, f"--material expects name=value, got {pair!r} (no '=')")
+        material[name] = value
+    body = plane.post(
+        "/v1/connections",
+        json={"connector": args.connector, "label": args.label, "material": material},
+    )
+    if not _as_json(args, body):
+        kind = "authless" if not material else "static"
+        print(f"created connection {body['label']} ({body['id']}) — {kind}, {body['status']}")
+    return 0
+
+
+def connection_bind(plane: ControlPlane, args: argparse.Namespace) -> int:
+    """Name what a workflow's connection: line means in one environment."""
+    plane.put(
+        f"/v1/projects/{args.project}/environments/{args.environment}/connections/{args.name}",
+        json={"connection_id": args.connection_id},
+    )
+    if not getattr(args, "json", False):
+        print(f"bound {args.name} → {args.connection_id} in {args.project}/{args.environment}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers.
+# ---------------------------------------------------------------------------
+
+
+def _resolve_user(plane: ControlPlane, who: str) -> str:
+    """A uuid, or the email of somebody in this tenant.
+
+    A person knows the address they invited; the id is in a response they have already
+    closed. Resolving here rather than making them look it up is the same argument
+    `RoleIn` makes about scopes — the lookup is what an API is for.
+    """
+    if "@" not in who:
+        return who
+    for user in plane.get("/v1/users"):
+        if user["email"] == who:
+            return str(user["id"])
+    raise ControlPlaneError(404, f"no user with the address {who} in this tenant")
+
+
+def _inputs(args: argparse.Namespace) -> dict[str, Any]:
+    inputs: dict[str, Any] = {}
+    for pair in args.input or []:
+        name, separator, value = pair.partition("=")
+        if not separator:
+            raise ControlPlaneError(0, f"--input takes name=value, not {pair!r}")
+        inputs[name] = value
+    if args.input_json is not None:
+        try:
+            decoded = json.loads(args.input_json)
+        except json.JSONDecodeError as exc:
+            raise ControlPlaneError(0, f"--input-json is not JSON: {exc}") from exc
+        if not isinstance(decoded, dict):
+            raise ControlPlaneError(0, "--input-json must be a JSON object of workflow inputs")
+        inputs.update(decoded)
+    return inputs
+
+
+def _scope(args: argparse.Namespace) -> str:
+    if args.environment is not None:
+        return f"{args.project}/{args.environment}"
+    if args.project is not None:
+        return f"project {args.project}"
+    return "the tenant"
+
+
+def _as_json(args: argparse.Namespace, payload: Any) -> bool:
+    if not getattr(args, "json", False):
+        return False
+    print(json.dumps(payload, indent=2, default=str))
+    return True
+
+
+def _table(headers: list[str], rows: list[list[str]]) -> None:
+    if not rows:
+        print("(none)")
+        return
+    widths = [
+        max(len(headers[column]), *(len(row[column]) for row in rows))
+        for column in range(len(headers))
+    ]
+    print("  ".join(header.ljust(widths[i]) for i, header in enumerate(headers)).rstrip())
+    for row in rows:
+        print("  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip())
+
+
+def _short(digest: str | None) -> str:
+    return digest[:12] if digest else DASH
+
+
+def _size(count: int) -> str:
+    if count < 1024:
+        return f"{count} bytes"
+    return f"{count / 1024:.1f} KiB"
+
+
+def _warn(message: str) -> None:
+    print(f"\n{message}", file=sys.stderr)

mkctl/config.py

@@ -0,0 +1,59 @@
+"""Where `mkctl` remembers how to reach a platform (`C32`).
+
+One file, three values, and a strict precedence: an explicit flag beats the
+environment, the environment beats this file, and this file beats asking the control
+plane. Only *discovered* values are ever written here — what a person set in a flag
+or a shell profile is theirs to manage, and a tool that copies it into a second
+location is a tool that creates drift between two places that both look
+authoritative. The day this module was written, the issuer and client id had changed
+under every shell profile that had them: discovery is the fix, this file is only its
+cache.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+
+def path() -> Path:
+    import os
+
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "mkctl" / "config.toml"
+
+
+def load() -> dict[str, str]:
+    try:
+        raw = path().read_bytes()
+    except FileNotFoundError:
+        return {}
+    try:
+        data = tomllib.loads(raw.decode())
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError):
+        # A corrupt cache is an empty cache, never a crash: everything in it can be
+        # re-discovered from the control plane it points at.
+        return {}
+    return {k: v for k, v in data.items() if isinstance(v, str)}
+
+
+def save(control_plane: str, issuer: str, client_id: str) -> None:
+    update(control_plane=control_plane, issuer=issuer, client_id=client_id)
+
+
+def update(**values: str) -> None:
+    """Merge into the file, keeping what is already there.
+
+    One writer shape for every key — the discovered endpoints and the advisory
+    bookkeeping (ADR 0014: `latest_seen`, `advised_at`) share the file because they
+    share the nature: facts the platform declared, safe to lose, re-learned on the
+    next login.
+    """
+    merged = {**load(), **values}
+    target = path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    lines = "".join(f'{key} = "{value}"\n' for key, value in sorted(merged.items()))
+    target.write_text(
+        "# Written by `mkctl login` from GET /v1/cli-config — a cache of what the\n"
+        "# control plane declared, safe to delete: login discovers it again.\n" + lines
+    )