mkctl 0.4.0__py3-none-any.whl

mkctl/__init__.py

@@ -0,0 +1,8 @@
+"""mkctl — the command line for the control plane.
+
+A human's terminal, which must not hold a password and must be revocable
+independently of the account (ADR 0004). It holds tokens the identity provider
+issued, in the OS keyring, and never a credential this platform minted.
+"""
+
+__version__ = "0.1.0"

mkctl/cli.py

@@ -0,0 +1,478 @@
+"""`mkctl` — log in, and then drive the control plane you logged into.
+
+`C14`. Until this, the CLI authenticated against an API it could not use: `login`,
+`logout` and `whoami` were the whole of it, which made the first thing a person does with
+this platform also the last. Every command below is a call to an endpoint that already
+existed — what was missing was the terminal, not the platform.
+
+Where the options come from is deliberate. A control plane, an issuer and a client id are
+per-installation and live in the environment; a project and an environment are per-command
+but almost always the same all day, so they take `MKCTL_PROJECT` and `MKCTL_ENVIRONMENT`
+as defaults. A role's scope does **not**: `mkctl role grant … ` with no scope means the
+tenant, and letting an environment variable widen or narrow a grant would make the same
+command give different power on two machines.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import importlib.metadata
+import os
+import sys
+from collections.abc import Callable
+from contextlib import suppress
+
+import httpx
+from mkp_contracts.roles import ROLES
+
+from . import client, commands, config
+from .client import ControlPlane, ControlPlaneError
+from .oauth import AuthorizationError
+from .session import Session
+from .store import StoreUnavailable, TokenStore
+
+CONTROL_PLANE_ENV = "MKCTL_CONTROL_PLANE"
+ISSUER_ENV = "MKCTL_OIDC_ISSUER"
+CLIENT_ID_ENV = "MKCTL_CLIENT_ID"
+PROJECT_ENV = "MKCTL_PROJECT"
+ENVIRONMENT_ENV = "MKCTL_ENVIRONMENT"
+
+Command = Callable[[ControlPlane, argparse.Namespace], int]
+
+
+def build_session(args: argparse.Namespace, *, allow_discovery: bool = False) -> Session:
+    """Resolve where and how to authenticate: flag > env > config file > discovery.
+
+    Discovery (`C32`) runs only for `login`, and only for what is still missing: the
+    control plane serves its own issuer and CLI client id at `GET /v1/cli-config`, so
+    the one value an operator needs is the URL. What discovery learns is cached in
+    `config.py`'s file; what a person set themselves never is — a copy of their
+    environment in a second location would just be drift waiting to disagree.
+    """
+    saved = config.load()
+    control_plane = (
+        args.control_plane or os.environ.get(CONTROL_PLANE_ENV) or saved.get("control_plane")
+    )
+    issuer = args.issuer or os.environ.get(ISSUER_ENV) or saved.get("issuer")
+    client_id = args.client_id or os.environ.get(CLIENT_ID_ENV) or saved.get("client_id")
+
+    if allow_discovery and control_plane and (not issuer or not client_id):
+        response = httpx.get(
+            f"{control_plane.rstrip('/')}/v1/cli-config",
+            timeout=10,
+            headers={"User-Agent": client.USER_AGENT},
+        )
+        if response.status_code == 404:
+            raise SystemExit(
+                "mkctl: this control plane declares no CLI configuration — "
+                f"pass --issuer and --client-id (or set ${ISSUER_ENV}, ${CLIENT_ID_ENV})"
+            )
+        response.raise_for_status()
+        declared = response.json()
+        issuer = issuer or declared["issuer"]
+        client_id = client_id or declared["client_id"]
+        config.save(control_plane, issuer, client_id)
+        print(f"Discovered issuer and client id from {control_plane} (cached)")
+
+    if not (control_plane and issuer and client_id):
+        missing = [
+            name
+            for name, value in (
+                (CONTROL_PLANE_ENV, control_plane),
+                (ISSUER_ENV, issuer),
+                (CLIENT_ID_ENV, client_id),
+            )
+            if not value
+        ]
+        raise SystemExit(
+            f"mkctl: set {', '.join(missing)} (or pass the matching option) — "
+            "or run `mkctl login --control-plane <url>` and let the platform say"
+        )
+    return Session(
+        control_plane=control_plane,
+        issuer=issuer,
+        client_id=client_id,
+        store=TokenStore(control_plane),
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="mkctl", description=(__doc__ or "").splitlines()[0])
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {importlib.metadata.version('mkctl')}",
+    )
+    parser.add_argument("--control-plane", help=f"or ${CONTROL_PLANE_ENV}")
+    parser.add_argument("--issuer", help=f"or ${ISSUER_ENV}")
+    parser.add_argument("--client-id", help=f"or ${CLIENT_ID_ENV}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    output = argparse.ArgumentParser(add_help=False)
+    output.add_argument(
+        "--json",
+        action="store_true",
+        help="the control plane's answer, unformatted — for scripts",
+    )
+
+    # -- the login itself ---------------------------------------------------
+    login = subparsers.add_parser("login", help="sign in through the identity provider")
+    login.add_argument(
+        "--device",
+        action="store_true",
+        help="use the device grant instead of a browser — for SSH and headless machines",
+    )
+    login.add_argument("--no-browser", action="store_true", help="print the URL, do not open it")
+
+    subparsers.add_parser("logout", help="revoke this device's token and forget it")
+    subparsers.add_parser(
+        "upgrade",
+        help="print the upgrade procedure for the latest release (ADR 0014)",
+    )
+    subparsers.add_parser("whoami", parents=[output], help="who the control plane thinks you are")
+
+    # -- bundles and the pointer -------------------------------------------
+    bundle = _group(subparsers, "bundle", "what `mkbundle build` produced")
+    push = bundle.add_parser("push", parents=[output], help="register a bundle and upload it")
+    push.add_argument("archive", help="the .tar.gz `mkbundle build` wrote")
+    _target(push, environment=False)
+
+    deploy = subparsers.add_parser(
+        "deploy", parents=[output], help="point an environment at a bundle"
+    )
+    deploy.add_argument("digest", help="the bundle's digest, which is its name")
+    _target(deploy)
+
+    # -- projects and environments -----------------------------------------
+    project = _group(subparsers, "project", "projects in this tenant")
+    project.add_parser("list", parents=[output], help="every project")
+    project_create = project.add_parser("create", parents=[output], help="a new project")
+    project_create.add_argument("slug")
+
+    environment = _group(subparsers, "env", "environments in a project")
+    _target(environment.add_parser("list", parents=[output], help="every environment"), False)
+    env_create = environment.add_parser("create", parents=[output], help="a new environment")
+    env_create.add_argument("name")
+    _target(env_create, environment=False)
+    env_get = environment.add_parser("get", parents=[output], help="what is deployed there")
+    env_get.add_argument("name")
+    _target(env_get, environment=False)
+
+    # -- runs ---------------------------------------------------------------
+    run = _group(subparsers, "run", "start, list, read, answer, or abandon")
+    start = run.add_parser("start", parents=[output], help="start a run of a deployed workflow")
+    start.add_argument("workflow")
+    start.add_argument(
+        "--input",
+        action="append",
+        metavar="NAME=VALUE",
+        help="a string input; repeatable",
+    )
+    start.add_argument(
+        "--input-json",
+        metavar="JSON",
+        help="the inputs as a JSON object, for anything that is not a string",
+    )
+    _target(start)
+
+    list_runs = run.add_parser("list", parents=[output], help="runs, newest first")
+    list_runs.add_argument("--status", help="filter by status (running, waiting, …)")
+    list_runs.add_argument("--project", help="filter by project name")
+    list_runs.add_argument("--environment", help="filter by environment name")
+    list_runs.add_argument("--workflow", help="filter by workflow name")
+    list_runs.add_argument("--limit", type=int, help="page size (API default 50, max 200)")
+    list_runs.add_argument("--cursor", help="continue a previous page")
+
+    get = run.add_parser("get", parents=[output], help="a run, its attempts, and what it waits on")
+    get.add_argument("run_id")
+
+    reply = run.add_parser("reply", parents=[output], help="reply to a waiting run")
+    reply.add_argument("run_id")
+    answer = reply.add_mutually_exclusive_group(required=True)
+    answer.add_argument("--text", help="what to tell the gate")
+    answer.add_argument("--json-payload", metavar="JSON", help="an answer that is not prose")
+    reply.add_argument(
+        "--step",
+        help="which gate, when a run waits on more than one",
+    )
+
+    abandon = run.add_parser("abandon", parents=[output], help="cancel a waiting run")
+    abandon.add_argument("run_id")
+    abandon.add_argument("--reason", help="why, recorded on the outbound row")
+
+    # -- people -------------------------------------------------------------
+    user = _group(subparsers, "user", "who is in this tenant")
+    user.add_parser("list", parents=[output], help="every user, and what each may do")
+    user_create = user.add_parser("create", parents=[output], help="mirror an IdP subject in")
+    user_create.add_argument("--subject", required=True, help="the IdP's subject claim")
+    user_create.add_argument("--email", required=True)
+
+    role = _group(subparsers, "role", "what a user may do, and where")
+    grant = role.add_parser("grant", parents=[output], help="give a user a role")
+    _role_arguments(grant)
+    revoke = role.add_parser("revoke", parents=[output], help="take a role away")
+    _role_arguments(revoke)
+
+    # -- above a tenant, and beside it --------------------------------------
+    tenant = _group(subparsers, "tenant", "needs the platform grant, not a role")
+    tenant.add_parser("list", parents=[output], help="every tenant")
+    tenant_create = tenant.add_parser("create", parents=[output], help="a tenant and its owner")
+    tenant_create.add_argument("slug")
+    tenant_create.add_argument("--owner-subject", required=True)
+    tenant_create.add_argument("--owner-email", required=True)
+    # `C15`. Omitted means unlimited — the honest default while every tenant is ours.
+    tenant_create.add_argument("--monthly-run-limit", type=int)
+    tenant_create.add_argument("--monthly-token-limit", type=int)
+
+    connection = _group(subparsers, "connection", "credentials, by label")
+    connection.add_parser("list", parents=[output], help="every connection in this tenant")
+    conn_create = connection.add_parser(
+        "create",
+        parents=[output],
+        help="store a credential (omit --material for auth: none)",
+    )
+    conn_create.add_argument(
+        "--connector", required=True, help="connector name (e.g. vendor, http)"
+    )
+    conn_create.add_argument("--label", required=True, help="human label in this tenant")
+    conn_create.add_argument(
+        "--material",
+        action="append",
+        metavar="NAME=VALUE",
+        help="credential field; repeatable. omit all for an authless connection (D10)",
+    )
+    conn_bind = connection.add_parser(
+        "bind",
+        parents=[output],
+        help="bind a connection name in an environment",
+    )
+    conn_bind.add_argument("name", help="the name workflows use (e.g. mailbox)")
+    conn_bind.add_argument(
+        "--connection-id",
+        required=True,
+        help="id from connection create/list",
+    )
+    _target(conn_bind)
+
+    return parser
+
+
+COMMANDS: dict[tuple[str, str | None], Command] = {
+    ("whoami", None): commands.whoami,
+    ("bundle", "push"): commands.bundle_push,
+    ("deploy", None): commands.deploy,
+    ("project", "list"): commands.project_list,
+    ("project", "create"): commands.project_create,
+    ("env", "list"): commands.environment_list,
+    ("env", "create"): commands.environment_create,
+    ("env", "get"): commands.environment_get,
+    ("run", "start"): commands.run_start,
+    ("run", "list"): commands.run_list,
+    ("run", "get"): commands.run_get,
+    ("run", "reply"): commands.run_reply,
+    ("run", "abandon"): commands.run_abandon,
+    ("user", "list"): commands.user_list,
+    ("user", "create"): commands.user_create,
+    ("role", "grant"): commands.role_grant,
+    ("role", "revoke"): commands.role_revoke,
+    ("tenant", "list"): commands.tenant_list,
+    ("tenant", "create"): commands.tenant_create,
+    ("connection", "list"): commands.connection_list,
+    ("connection", "create"): commands.connection_create,
+    ("connection", "bind"): commands.connection_bind,
+}
+
+
+def main(argv: list[str] | None = None, *, session: Session | None = None) -> int:
+    """Parse, then dispatch.
+
+    `session` is a seam for the tests and nothing else: it lets a test drive the real
+    parser and the real dispatch table over real HTTP without reaching for the machine's
+    keyring, which `build_session` would otherwise do (`store.py`).
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "upgrade":
+        return _upgrade(args)
+    try:
+        session = session or build_session(args, allow_discovery=args.command == "login")
+        if args.command not in ("login", "logout"):
+            _advise_if_stale()
+        if args.command == "login":
+            return _login(session, args)
+        if args.command == "logout":
+            return _logout(session)
+        command = COMMANDS[(args.command, getattr(args, "subcommand", None))]
+        return command(ControlPlane(session=session), args)
+    except KeyboardInterrupt:
+        # Login (and device poll) wait on the human; Ctrl+C is a clean cancel, not a crash.
+        print("\nmkctl: cancelled", file=sys.stderr)
+        return 130
+    except StoreUnavailable as exc:
+        print(f"mkctl: {exc}", file=sys.stderr)
+        return 2
+    except (AuthorizationError, ControlPlaneError) as exc:
+        print(f"mkctl: {exc}", file=sys.stderr)
+        return 1
+    except httpx.HTTPError as exc:
+        print(f"mkctl: {exc}", file=sys.stderr)
+        return 2
+
+
+def _login(session: Session, args: argparse.Namespace) -> int:
+    session.login(device=args.device, open_browser=not args.no_browser)
+    print(f"Signed in to {session.control_plane}")
+    _advise_from_platform(session.control_plane)
+    return 0
+
+
+def _own_version() -> str:
+    return client.USER_AGENT.removeprefix("mkctl/")
+
+
+def _advise_from_platform(control_plane: str) -> None:
+    """ADR 0014: one line, at login, best-effort — advice never fails a command."""
+    try:
+        response = httpx.get(
+            f"{control_plane.rstrip('/')}/v1/cli-config",
+            timeout=10,
+            headers={"User-Agent": client.USER_AGENT},
+        )
+        latest = response.json().get("cli", {}).get("latest", "")
+    except Exception:
+        # Advisory only: any failure here is silence, never a crash.
+        return
+    if not latest:
+        return
+    config.update(latest_seen=latest, advised_at=dt.datetime.now(dt.UTC).isoformat())
+    _print_advice_if_newer(latest)
+
+
+def _advise_if_stale() -> None:
+    """Between logins: cached knowledge only, at most once a day, zero network."""
+    saved = config.load()
+    latest = saved.get("latest_seen", "")
+    if not latest:
+        return
+    advised = saved.get("advised_at", "")
+    try:
+        if advised and dt.datetime.now(dt.UTC) - dt.datetime.fromisoformat(advised) < dt.timedelta(
+            days=1
+        ):
+            return
+    except ValueError:
+        pass
+    if _print_advice_if_newer(latest):
+        config.update(advised_at=dt.datetime.now(dt.UTC).isoformat())
+
+
+def _print_advice_if_newer(latest: str) -> bool:
+    from mkp_contracts import cli_versions
+
+    mine, theirs = cli_versions.parse(_own_version()), cli_versions.parse(latest)
+    if mine is None or theirs is None or mine >= theirs:
+        return False
+    print(
+        f"mkctl {_own_version()} — {latest} is available; run `mkctl upgrade` for the procedure",
+        file=sys.stderr,
+    )
+    return True
+
+
+def _upgrade(args: argparse.Namespace) -> int:
+    """Print the procedure, perform nothing (ADR 0014, Amendment 1).
+
+    The index exists since 0.4.0, so the procedure is one line instead of four and
+    involves nobody's GitHub token. It still prints rather than performs, and that is
+    the amendment rather than an omission: an upgrade has to know *how* this was
+    installed — pipx, pip inside a virtualenv, `uv tool` — and a CLI that guesses
+    upgrades the wrong environment. Printing is also what keeps this command honest
+    when the answer is "you did not install it, your package manager did".
+    """
+    latest = config.load().get("latest_seen", "")
+    control_plane = (
+        args.control_plane
+        or os.environ.get(CONTROL_PLANE_ENV)
+        or config.load().get("control_plane")
+    )
+    if control_plane:
+        # Best-effort refresh; the cached answer is still an answer.
+        with suppress(httpx.HTTPError, ValueError, KeyError):
+            response = httpx.get(
+                f"{control_plane.rstrip('/')}/v1/cli-config",
+                timeout=10,
+                headers={"User-Agent": client.USER_AGENT},
+            )
+            latest = response.json().get("cli", {}).get("latest", latest)
+    print(f"mkctl {_own_version()} installed; latest declared: {latest or 'unknown'}")
+    print("\nUpgrade:")
+    print(f"  pipx upgrade mkctl{f'  # to {latest}' if latest else ''}")
+    print("\nor, if this was installed some other way:")
+    print("  pip install --upgrade mkctl")
+    return 0
+
+
+def _logout(session: Session) -> int:
+    revoked = session.logout()
+    if revoked:
+        print("Token revoked and forgotten")
+    else:
+        # Worth distinguishing: the local copy is gone either way, but a token the
+        # provider never heard about being revoked is still live somewhere.
+        print("Local token forgotten; the provider did not confirm revocation", file=sys.stderr)
+    return 0
+
+
+def _group(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+    name: str,
+    help_text: str,
+) -> argparse._SubParsersAction[argparse.ArgumentParser]:
+    """A noun with verbs under it: `mkctl run start`, `mkctl run reply`."""
+    parser = subparsers.add_parser(name, help=help_text)
+    return parser.add_subparsers(dest="subcommand", required=True)
+
+
+def _target(parser: argparse.ArgumentParser, environment: bool = True) -> None:
+    """`--project` and `--env`, defaulted from the environment.
+
+    Required, and checked by argparse rather than by each command: a missing project is
+    a usage error and should read like one instead of arriving as a 404 for a path with
+    the word `None` in it.
+    """
+    parser.add_argument(
+        "--project",
+        default=os.environ.get(PROJECT_ENV),
+        required=PROJECT_ENV not in os.environ,
+        help=f"or ${PROJECT_ENV}",
+    )
+    if environment:
+        parser.add_argument(
+            "--env",
+            dest="environment",
+            default=os.environ.get(ENVIRONMENT_ENV),
+            required=ENVIRONMENT_ENV not in os.environ,
+            help=f"or ${ENVIRONMENT_ENV}",
+        )
+
+
+def _role_arguments(parser: argparse.ArgumentParser) -> None:
+    """A user, a role, and the scope — which has no environment default on purpose."""
+    parser.add_argument("user", help="a user id, or the email of somebody in this tenant")
+    # Both the help and the accepted set come from `mkp_contracts.roles`, which is now
+    # the one place the four names live (ADR 0004). `choices=` was the wrong call while
+    # this list was a local copy — a fourth copy of a name list is what `prod pin` had to
+    # be fixed for — and is the right one now that there is nothing to drift from: a
+    # wrong role fails in the terminal, naming the four, instead of at the API.
+    parser.add_argument("role", choices=ROLES, help=f"{', '.join(ROLES)} (ADR 0004)")
+    parser.add_argument("--project", help="scope the role to one project")
+    parser.add_argument(
+        "--env",
+        dest="environment",
+        help="scope it to one environment; needs --project, since names repeat across them",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mkctl/client.py

@@ -0,0 +1,131 @@
+"""Driving the control plane with a login that is already held.
+
+One place adds the bearer, and one place turns a refusal into something a person can
+read. Both matter more than they look:
+
+* the token comes from `Session.access_token()`, which refreshes when it is due — so a
+  long-running command cannot be the thing that discovers the session expired, and no
+  command has its own idea of where a token lives (ADR 0004: the keyring, and nowhere
+  else).
+* the control plane's refusals are structured. A deploy rejected by the deploy rules
+  answers with `{"detail": {"rejected": [...]}}` because ADR 0005 requires the reason to
+  name the constraint, and a CLI that printed that dictionary as Python would throw the
+  reason away at the last step of the journey it was written for.
+
+The one thing this deliberately does not do is compute a bundle's digest. The control
+plane recomputes it from the manifest and returns it (`routes.py:_verify_digest`), so the
+archive is uploaded under the name the server gave it. A second opinion here would be a
+second definition of a bundle's identity, which is the thing `mkp-contracts` exists to
+prevent.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from .session import Session
+
+TIMEOUT = 60
+
+
+class ControlPlaneError(Exception):
+    """The control plane refused, and said why."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+# ADR 0014: the CLI names itself on every request. Not trusted, not authentication —
+# it is what lets the control plane answer "upgrade" instead of a validation error.
+USER_AGENT = f"mkctl/{importlib.metadata.version('mkctl')}"
+
+
+@dataclass
+class ControlPlane:
+    """Authenticated requests against one control plane."""
+
+    session: Session
+    client: httpx.Client | None = None
+    _token: str | None = field(default=None, init=False, repr=False)
+
+    @property
+    def base_url(self) -> str:
+        return self.session.control_plane.rstrip("/")
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PUT", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        content: bytes | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        if self._token is None:
+            self._token = self.session.access_token()
+        headers = {"Authorization": f"Bearer {self._token}", "User-Agent": USER_AGENT}
+        request = {"json": json, "content": content, "params": params, "headers": headers}
+        if self.client is not None:
+            response = self.client.request(method, f"{self.base_url}{path}", **request)
+        else:
+            with httpx.Client(timeout=TIMEOUT) as http:
+                response = http.request(method, f"{self.base_url}{path}", **request)
+        if response.status_code >= 400:
+            raise _refusal(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+
+def _refusal(response: httpx.Response) -> ControlPlaneError:
+    if response.status_code == 426:
+        # ADR 0014: the platform stopped serving this mkctl. The detail already
+        # names the versions and the command; pass it through untouched.
+        return ControlPlaneError(426, _reason(response))
+    if response.status_code == 401:
+        # Distinguished from every other refusal because the remedy is different: a 403
+        # is "you may not", and only this one is "you are nobody yet".
+        return ControlPlaneError(401, "the control plane rejected this token — run `mkctl login`")
+    return ControlPlaneError(response.status_code, _reason(response))
+
+
+def _reason(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text.strip() or f"HTTP {response.status_code}"
+
+    detail = body.get("detail", body) if isinstance(body, dict) else body
+    if isinstance(detail, dict) and "rejected" in detail:
+        # The deploy rules, the trigger registration and `D4` all answer this way. Each
+        # entry names one constraint, and all of them are the answer — printing only the
+        # first would send somebody back for a second attempt that fails on the second.
+        reasons = detail["rejected"]
+        return "refused:\n" + "\n".join(f"  - {reason}" for reason in reasons)
+    if isinstance(detail, list):
+        # FastAPI's own validation errors, which is what a mistyped input looks like.
+        return "; ".join(
+            f"{'.'.join(str(part) for part in item.get('loc', [])[1:])}: {item.get('msg', '')}"
+            for item in detail
+        )
+    return str(detail)
+
+
+__all__ = ["ControlPlane", "ControlPlaneError"]