apizit-cli 0.2.0b1__py3-none-any.whl

apizit_cli/operations.py

@@ -0,0 +1,745 @@
+"""Command orchestration; authorization and product decisions stay on the server."""
+
+from __future__ import annotations
+
+import getpass
+import hashlib
+import json
+import os
+import sys
+import tempfile
+import time
+import uuid
+import webbrowser
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import requests
+import yaml
+
+from apizit_cli import __version__
+from apizit_cli.authentication import system_vault
+from apizit_cli.commands import COMMANDS
+from apizit_cli.configuration import (
+    CONFIG_FILES,
+    DeploymentConfiguration,
+    load_configuration,
+    _StrictLoader,
+)
+from apizit_cli.context import ClientContext
+from apizit_cli.errors import CliError, EXIT_CONFLICT, EXIT_NETWORK, EXIT_TIMEOUT, EXIT_USAGE
+from apizit_cli.http import PlatformClient, identifier
+
+
+def launch_overrides(args):
+    result = {}
+    if getattr(args, "region", None) is not None:
+        result["region"] = args.region
+    if getattr(args, "format", None) is not None:
+        result["launch"] = {"format": args.format}
+    if getattr(args, "name", None) is not None:
+        result["project"] = {"name": args.name}
+    if getattr(args, "api_key_required", False) and getattr(args, "no_api_key", False):
+        raise CliError("Choose --api-key-required or --no-api-key.", exit_code=EXIT_USAGE)
+    if getattr(args, "api_key_required", False):
+        result["api"] = {"api_key_required": True}
+    elif getattr(args, "no_api_key", False):
+        result["api"] = {"api_key_required": False}
+    return result
+
+
+class CommandRunner:
+    def __init__(self, args, *, client=None):
+        self.args = args
+        source = getattr(args, "directory", None) or getattr(args, "source", None)
+        root = Path(source) if source and Path(source).is_dir() else None
+        self.context = (
+            client.context
+            if client
+            else ClientContext(
+                workspace_id=getattr(args, "workspace", None),
+                endpoint=getattr(args, "endpoint", None),
+                root=root,
+            )
+        )
+        self.client = client or PlatformClient(self.context)
+        self.tracking = {}
+        self.non_interactive = bool(
+            getattr(args, "non_interactive", False)
+            or getattr(args, "json", False)
+            or not sys.stdin.isatty()
+        )
+        if getattr(args, "token_stdin", False):
+            if getattr(args, "stdin", False):
+                raise CliError(
+                    "stdin cannot carry both a token and a secret.", exit_code=EXIT_USAGE
+                )
+            if sys.stdin.isatty():
+                raise CliError("Pipe a token to --token-stdin.", exit_code=EXIT_USAGE)
+            token = sys.stdin.read(8193).strip()
+            if not token or len(token) > 8192:
+                raise CliError("Expected a bounded CI token on stdin.", exit_code=EXIT_USAGE)
+            self.client.auth.injected_token = token
+        if getattr(args, "wait", False) and getattr(args, "no_wait", False):
+            raise CliError("Choose --wait or --no-wait.", exit_code=EXIT_USAGE)
+
+    def get(self, path, **kwargs):
+        return self.client.request("GET", path, **kwargs)
+
+    def operation_key(self):
+        key = getattr(self.args, "idempotency_key", None)
+        if key is None:
+            key = self.tracking.get("idempotency_key") or str(uuid.uuid4())
+        if not 8 <= len(key) <= 128 or not all(
+            c.isascii() and (c.isalnum() or c in "._:-") for c in key
+        ):
+            raise CliError(
+                "An idempotency key must be 8–128 ASCII letters, digits or ._:-.",
+                exit_code=EXIT_USAGE,
+            )
+        self.tracking["idempotency_key"] = key
+        return key
+
+    def confirm(self, message):
+        if getattr(self.args, "yes", False):
+            return
+        if self.non_interactive:
+            raise CliError(
+                "This action requires --yes in scripts or JSON mode.",
+                code="CONFIRMATION_REQUIRED",
+                exit_code=EXIT_USAGE,
+            )
+
+        print(message + ' Type "yes" to continue: ', end="", file=sys.stderr, flush=True)
+        if sys.stdin.readline().strip() != "yes":
+            raise CliError(
+                "No operation was submitted.", code="CONFIRMATION_DECLINED", exit_code=EXIT_USAGE
+            )
+
+    def phase_key(self, phase):
+        return hashlib.sha256((self.operation_key() + "\n" + phase).encode()).hexdigest()
+
+    def api_id(self, value=None):
+        result = value or getattr(self.args, "api", None) or self.context.project.get("api_id")
+        if not result:
+            raise CliError(
+                "Provide an API ID or link this project with deploy.",
+                code="API_REQUIRED",
+                exit_code=EXIT_USAGE,
+            )
+        return identifier(result)
+
+    def should_wait(self):
+        return bool(
+            getattr(self.args, "wait", False)
+            or (not getattr(self.args, "no_wait", False) and not self.non_interactive)
+        )
+
+    def submitted(self, result, *, scan=False):
+        for key in ("scan_id", "job_id", "api_id", "deployment_id", "source_snapshot_id"):
+            if result.get(key):
+                self.tracking[key] = result[key]
+        if self.should_wait():
+            resource_id = result.get("scan_id" if scan else "job_id")
+            if resource_id:
+                result = {**result, "operation": self.wait(resource_id, scan=scan)}
+        return result
+
+    def wait(self, resource_id, *, scan=False):
+        kind = "scan" if scan else "job"
+        self.tracking[kind + "_id"] = resource_id
+        deadline = time.monotonic() + (getattr(self.args, "timeout", None) or 600)
+        previous = None
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise CliError(
+                    f"Local wait expired. Resume with apizit {kind} wait {resource_id}.",
+                    code="WAIT_TIMEOUT",
+                    exit_code=EXIT_TIMEOUT,
+                    details=dict(self.tracking),
+                )
+            result = self.get(f"/{kind}s/{identifier(resource_id)}", timeout=min(30, remaining))
+            status = result.get("status")
+            if not isinstance(status, str):
+                raise CliError(
+                    "Operation status is missing.", code="INVALID_RESPONSE", exit_code=EXIT_NETWORK
+                )
+            if status != previous:
+                print(
+                    json.dumps({"operation": kind, "id": resource_id, "status": status}),
+                    file=sys.stderr,
+                    flush=True,
+                )
+                previous = status
+            if status == "SUCCEEDED":
+                return result
+            if status in {"FAILED", "CANCELLED", "RECONCILIATION_REQUIRED", "DEAD_LETTERED"}:
+                raise CliError(
+                    "The remote operation finished without success; inspect its result.",
+                    code="OPERATION_" + status,
+                    details={**self.tracking, "operation": result},
+                )
+            time.sleep(min(2, max(0, deadline - time.monotonic())))
+
+    def prepare_source(self, source):
+        if source.startswith("https://"):
+            result = self.client.request(
+                "POST",
+                "/sources",
+                body={
+                    "kind": "git",
+                    "repository_url": source,
+                    **({"ref": self.args.ref} if getattr(self.args, "ref", None) else {}),
+                },
+                idempotency_key=self.phase_key("source"),
+            )
+        else:
+            if getattr(self.args, "ref", None):
+                raise CliError(
+                    "--ref applies to Git URLs, not local folders.", exit_code=EXIT_USAGE
+                )
+            from apizit_cli.sources import pack_local_source
+
+            root = Path(source).resolve(strict=True)
+            if not root.is_dir():
+                raise CliError("Source must be a folder or HTTPS Git URL.", exit_code=EXIT_USAGE)
+            # Validate before upload; the server validates the exact uploaded bytes again.
+            load_configuration(root)
+            with tempfile.TemporaryDirectory(prefix="apizit-source-") as temporary:
+                bundle = pack_local_source(root, Path(temporary) / "source.tar.gz")
+                manifest = bundle.path.with_suffix(
+                    bundle.path.suffix + ".manifest.json"
+                ).read_bytes()
+                result = self.client.request(
+                    "POST",
+                    "/sources",
+                    body={
+                        "kind": "local",
+                        "digest_sha256": bundle.digest_sha256,
+                        "size_bytes": bundle.size_bytes,
+                        "manifest_sha256": hashlib.sha256(manifest).hexdigest(),
+                        "source_commit_sha": bundle.source_commit_sha,
+                        "working_tree_dirty": bundle.working_tree_dirty,
+                    },
+                    idempotency_key=self.phase_key("source"),
+                )
+                self.tracking["source_snapshot_id"] = result["source_snapshot_id"]
+                if result.get("status") == "UPLOADING":
+                    upload = result["upload"]
+                    _trusted_delivery_url(upload["url"])
+                    transport = requests.Session()
+                    transport.trust_env = False
+                    try:
+                        with bundle.path.open("rb") as stream:
+                            response = transport.post(
+                                upload["url"],
+                                data=upload["fields"],
+                                files={"file": ("source.tar.gz", stream, "application/gzip")},
+                                timeout=120,
+                                allow_redirects=False,
+                            )
+                        if response.status_code not in {200, 201, 204}:
+                            raise requests.RequestException()
+                    except requests.RequestException:
+                        raise CliError(
+                            "Source upload was not confirmed. Retry with the same idempotency key.",
+                            code="SOURCE_UPLOAD_FAILED",
+                            exit_code=EXIT_NETWORK,
+                        ) from None
+                    finally:
+                        transport.close()
+                    result = self.client.request(
+                        "POST",
+                        f"/sources/{identifier(result['source_snapshot_id'])}/finalize",
+                        body={},
+                        idempotency_key=self.phase_key("finalize"),
+                    )
+        self.tracking["source_snapshot_id"] = result["source_snapshot_id"]
+        deadline = time.monotonic() + (getattr(self.args, "timeout", None) or 600)
+        previous = None
+        while result.get("status") != "READY":
+            status = result.get("status")
+            if status in {"FAILED", "EXPIRED"}:
+                raise CliError(
+                    "Source preparation failed; inspect the source and configuration.",
+                    code=result.get("failure_code") or "SOURCE_PREPARATION_FAILED",
+                )
+            if status != previous:
+                print(
+                    json.dumps(
+                        {"source_snapshot_id": result["source_snapshot_id"], "status": status}
+                    ),
+                    file=sys.stderr,
+                    flush=True,
+                )
+                previous = status
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise CliError(
+                    "Source preparation is still running. Retry with the same idempotency key.",
+                    code="WAIT_TIMEOUT",
+                    exit_code=EXIT_TIMEOUT,
+                )
+            time.sleep(min(1, remaining))
+            result = self.get(
+                f"/sources/{identifier(result['source_snapshot_id'])}", timeout=min(30, remaining)
+            )
+        return result
+
+    def run(self):
+        args, command = self.args, self.args.command_path
+        if command == "login":
+            return self.client.auth.login(
+                timeout=getattr(args, "timeout", None) or 180,
+                non_interactive=self.non_interactive,
+            )
+        if command == "logout":
+            return self.client.auth.logout()
+        if command == "whoami":
+            return self.get("/auth/me", workspace=False)
+        if command == "workspace list":
+            return self.get("/workspaces", workspace=False)
+        if command == "workspace use":
+            workspaces = self.get("/workspaces", workspace=False).get("workspaces", [])
+            selected = next(
+                (item for item in workspaces if item.get("workspace_id") == args.id), None
+            )
+            if selected is None:
+                raise CliError(
+                    "Workspace is not accessible.", code="WORKSPACE_NOT_FOUND", exit_code=4
+                )
+            if (
+                self.context.project.get("api_id")
+                and self.context.project.get("workspace_id") != args.id
+            ):
+                raise CliError(
+                    "This project's API belongs to another workspace.",
+                    code="PROJECT_WORKSPACE_MISMATCH",
+                    exit_code=EXIT_USAGE,
+                )
+            self.context.select_workspace(args.id)
+            return {"workspace": selected}
+        if command == "workspace show":
+            return self.get("/workspace/current")
+        if command == "workspace create":
+            return self.client.request(
+                "POST", "/workspaces", body={"name": args.name}, workspace=False
+            )
+        if command.startswith("config ") or command == "init":
+            return self.configuration()
+        if command == "scan":
+            if args.source in {"show", "wait"}:
+                if not args.id or any(
+                    getattr(args, key, None)
+                    for key in ("ref", "format", "region", "idempotency_key")
+                ):
+                    raise CliError(
+                        "Use scan show/wait <id> without source options.", exit_code=EXIT_USAGE
+                    )
+                return (
+                    self.wait(args.id, scan=True)
+                    if args.source == "wait"
+                    else self.get(f"/scans/{identifier(args.id)}")
+                )
+            if args.id:
+                raise CliError("Provide exactly one source.", exit_code=EXIT_USAGE)
+            source = self.prepare_source(args.source)
+            result = self.client.request(
+                "POST",
+                "/scans",
+                body={
+                    "source_snapshot_id": source["source_snapshot_id"],
+                    "configuration_overrides": launch_overrides(args),
+                },
+                idempotency_key=self.operation_key(),
+            )
+            return self.submitted(result, scan=True)
+        if command == "deploy":
+            return self.deploy()
+        if command.startswith("api ") or command.startswith("release "):
+            return self.api_command()
+        if command in {"job show", "job wait"}:
+            return (
+                self.wait(args.id)
+                if command.endswith("wait")
+                else self.get(f"/jobs/{identifier(args.id)}")
+            )
+        if command == "job cancel":
+            job = self.get(f"/jobs/{identifier(args.id)}")
+            if job.get("target", {}).get("type") != "deployment" or (
+                not job.get("can_cancel") and not args.idempotency_key
+            ):
+                raise CliError(
+                    "This operation cannot currently be cancelled.",
+                    code="JOB_NOT_CANCELLABLE",
+                    exit_code=EXIT_CONFLICT,
+                )
+            self.confirm("Request cancellation of this operation?")
+            target = identifier(job["target"]["id"])
+            result = self.client.request(
+                "POST",
+                f"/deployments/{target}/jobs/{identifier(args.id)}/cancel",
+                body={},
+                idempotency_key=self.operation_key(),
+            )
+            return self.submitted(result)
+        if command == "regions":
+            # This translation expresses product names, never plan limits.
+            formats = {
+                "automatic": ("auto", "automatic"),
+                "standard": ("lambda_zip", "automatic"),
+                "expanded": ("lambda_ecr", "automatic"),
+                "max_power": ("lambda_ecr", "max_power"),
+            }
+            launch_type, performance = formats[args.format or "automatic"]
+            query = {"deployment_type": launch_type, "performance_profile": performance}
+            if args.api:
+                query["api_id"] = args.api
+            return self.get("/deployments/regions", query=query)
+        if command == "plans":
+            return self.get("/subscriptions/plans", workspace=False, authenticated=False)
+        if command == "usage":
+            return self.get("/deployments/usage")
+        if command == "capabilities":
+            return self.get("/capabilities")
+        if command.startswith("token ") or command.startswith("secret "):
+            return self.access_command()
+        if command == "docs":
+            configuration = self.client.auth.configuration()
+            url = configuration["website_url"].rstrip("/") + "/cli/"
+            if args.topic:
+                topic = args.topic.strip().lower()
+                if topic in {item.path for item in COMMANDS}:
+                    url += "commands/#" + topic.replace(" ", "-")
+                elif topic in {
+                    "installation",
+                    "commands",
+                    "configuration",
+                    "sources",
+                    "workspaces",
+                    "releases",
+                    "observability",
+                    "access",
+                    "agents",
+                    "ci",
+                    "troubleshooting",
+                }:
+                    url += topic + "/"
+                elif topic != "quickstart":
+                    raise CliError(
+                        "Unknown documentation topic or command.",
+                        code="DOCS_TOPIC_INVALID",
+                        exit_code=EXIT_USAGE,
+                    )
+            if args.open:
+                if self.non_interactive:
+                    raise CliError("--open requires an interactive terminal.", exit_code=EXIT_USAGE)
+                webbrowser.open(url)
+            return {"url": url, "version": __version__, "status": "beta"}
+        if command == "doctor":
+            checks = {
+                "client_version": __version__,
+                "python": sys.version.split()[0],
+                "endpoint": self.context.origin,
+            }
+            try:
+                checks["connection"] = {
+                    "ok": True,
+                    "configuration_version": self.client.auth.configuration()["version"],
+                }
+            except CliError as error:
+                checks["connection"] = {"ok": False, "code": error.code}
+            if self.client.auth.injected_token:
+                checks["credential_vault"] = {"ok": True, "required": False}
+            else:
+                try:
+                    system_vault()
+                    checks["credential_vault"] = {"ok": True, "required": True}
+                except CliError as error:
+                    checks["credential_vault"] = {"ok": False, "code": error.code}
+            if any(
+                isinstance(check, dict) and check.get("ok") is False for check in checks.values()
+            ):
+                raise CliError(
+                    "A required client check failed.", code="DOCTOR_CHECK_FAILED", details=checks
+                )
+            return checks
+        raise CliError("Unknown command.", exit_code=EXIT_USAGE)
+
+    def configuration(self):
+        args = self.args
+        if args.command_path == "config schema":
+            return DeploymentConfiguration.model_json_schema()
+        root = Path(args.directory or ".").resolve(strict=True)
+        if args.command_path == "init":
+            if any((root / name).exists() for name in CONFIG_FILES):
+                raise CliError(
+                    "A deployment configuration already exists.",
+                    code="CONFIG_EXISTS",
+                    exit_code=EXIT_CONFLICT,
+                )
+            name = args.name or root.name
+            from apizit_cli.configuration import parse_configuration
+
+            value = {"version": 2, "project": {"name": name}, "launch": {"format": "automatic"}}
+            parse_configuration(json.dumps(value), json_format=True)
+            import yaml
+
+            path = root / CONFIG_FILES[0]
+            with path.open("x", encoding="utf-8", newline="\n") as stream:
+                yaml.safe_dump(value, stream, sort_keys=False, allow_unicode=True)
+            return {"path": str(path), "version": 2}
+        config, path = load_configuration(root)
+        if args.command_path == "config validate":
+            return {"valid": True, "path": str(path) if path else None, "version": 2}
+        body = {"configuration": config.explicit_options(), "overrides": launch_overrides(args)}
+        api = getattr(args, "api", None) or self.context.project.get("api_id")
+        if api:
+            body["api_id"] = api
+        return self.client.request("POST", "/configuration/resolve", body=body)
+
+    def deploy(self):
+        args = self.args
+        api = args.api or self.context.project.get("api_id")
+        if args.from_scan and (args.source or args.ref):
+            raise CliError(
+                "--from-scan cannot be combined with a source or --ref.", exit_code=EXIT_USAGE
+            )
+        if args.strategy and not api:
+            raise CliError(
+                "--strategy applies to a release of an existing API.", exit_code=EXIT_USAGE
+            )
+        if api and (args.strategy or "direct") == "direct":
+            self.confirm("Launch a release that replaces this API's live traffic?")
+        body = {"configuration_overrides": launch_overrides(args)}
+        if args.from_scan:
+            body["from_scan_id"] = args.from_scan
+        else:
+            source = self.prepare_source(args.source or ".")
+            body["source_snapshot_id"] = source["source_snapshot_id"]
+        if args.strategy:
+            body["deployment_strategy"] = args.strategy
+        route = f"/apis/{identifier(api)}/deploy" if api else "/deployments"
+        result = self.client.request("POST", route, body=body, idempotency_key=self.operation_key())
+        self.tracking.update(
+            {key: result[key] for key in ("api_id", "job_id", "deployment_id") if result.get(key)}
+        )
+        if (
+            result.get("api_id")
+            and not args.from_scan
+            and not (args.source or ".").startswith("https://")
+        ):
+            self.context.bind_api(result["api_id"])
+        result = self.submitted(result)
+        if self.should_wait() and result.get("api_id"):
+            result["api"] = self.get(f"/apis/{identifier(result['api_id'])}")
+        return result
+
+    def api_command(self):
+        args, command = self.args, self.args.command_path
+        if command == "api list":
+            return self.get("/apis")
+        if command == "release show":
+            return self.get(f"/deployments/{identifier(args.id)}")
+        if command == "release discard":
+            self.confirm("Delete this retained release?")
+            return self.submitted(
+                self.client.request(
+                    "DELETE",
+                    f"/deployments/{identifier(args.id)}",
+                    idempotency_key=self.operation_key(),
+                )
+            )
+        api = self.api_id(getattr(args, "id", None) if command.startswith("api ") else None)
+        if command == "api show":
+            return self.get(f"/apis/{api}")
+        if command == "api logs":
+            fields = {
+                "from": "from",
+                "to": "to",
+                "level": "level",
+                "query": "q",
+                "limit": "limit",
+                "cursor": "cursor",
+                "release": "deployment_id",
+            }
+            return self.get(
+                f"/apis/{api}/logs",
+                query={
+                    target: getattr(args, source)
+                    for source, target in fields.items()
+                    if getattr(args, source, None) is not None
+                },
+            )
+        if command == "api usage":
+            return self.get(f"/apis/{api}/dashboard").get("usage", {})
+        if command == "api key":
+            release = args.release
+            if not release:
+                release = (self.get(f"/apis/{api}").get("current_deployment") or {}).get(
+                    "deployment_id"
+                )
+            if not release:
+                raise CliError("This API has no active release.", code="RELEASE_NOT_FOUND")
+            return self.get(f"/apis/{api}/deployments/{identifier(release)}/credentials")
+        if command == "api openapi":
+            delivery = self.get(f"/apis/{api}/artifacts/openapi/export")
+            document = _download_openapi(delivery["url"])
+            if args.output:
+                output = Path(args.output)
+                with output.open("x", encoding="utf-8") as stream:
+                    json.dump(document, stream, indent=2)
+                    stream.write("\n")
+                return {"path": str(output.resolve()), "api_id": api}
+            return {"api_id": api, "openapi": document}
+        if command == "api delete":
+            self.confirm("Delete this API and its releases?")
+            return self.submitted(
+                self.client.request("DELETE", f"/apis/{api}", idempotency_key=self.operation_key())
+            )
+        detail = self.get(f"/apis/{api}")
+        workflow = detail.get("release_workflow", {})
+        if command == "release list":
+            return {"api_id": api, "releases": detail.get("deployments", []), "workflow": workflow}
+        promoting = command == "release promote"
+        capability = "can_promote" if promoting else "can_rollback"
+        if not workflow.get(capability) and not args.idempotency_key:
+            raise CliError(
+                "This traffic change is not currently allowed.",
+                code=workflow.get("promotion_blocker" if promoting else "rollback_blocker")
+                or "TRAFFIC_CHANGE_BLOCKED",
+                exit_code=EXIT_CONFLICT,
+            )
+        body = {"expected_active_deployment_id": workflow["active_deployment_id"]}
+        if promoting:
+            if workflow.get("candidate_deployment_id") != args.id and not args.idempotency_key:
+                raise CliError(
+                    "The selected release is not the current candidate.",
+                    code="CANDIDATE_CHANGED",
+                    exit_code=EXIT_CONFLICT,
+                )
+            path = f"/apis/{api}/deployments/{identifier(args.id)}/promote"
+        else:
+            body["expected_rollback_target_id"] = (
+                workflow.get("rollback_target_id") or workflow["active_deployment_id"]
+            )
+            path = f"/apis/{api}/rollback"
+        self.confirm("Change this API's live traffic to the selected existing release?")
+        # The server freezes the first preconditions and replays the recorded result.
+        return self.submitted(
+            self.client.request("POST", path, body=body, idempotency_key=self.operation_key())
+        )
+
+    def access_command(self):
+        args, command = self.args, self.args.command_path
+        if command == "token create":
+            body = {"name": args.name}
+            if args.scope is not None:
+                body["scopes"] = args.scope
+            if args.expires_days is not None:
+                body["expires_in_days"] = args.expires_days
+            return self.client.request("POST", "/workspace/tokens", body=body)
+        if command == "token list":
+            return self.get("/workspace/tokens")
+        if command == "token revoke":
+            self.confirm("Revoke this automation token?")
+            return self.client.request("DELETE", f"/workspace/tokens/{identifier(args.id)}")
+        if command == "secret list":
+            return self.get("/workspace/secrets")
+        if command == "secret delete":
+            self.confirm("Delete this secret if no retained release needs it?")
+            return self.client.request(
+                "DELETE",
+                f"/workspace/secrets/{identifier(args.name)}",
+                idempotency_key=self.operation_key(),
+            )
+        if args.stdin and args.from_env:
+            raise CliError("Choose --stdin or --from-env.", exit_code=EXIT_USAGE)
+        if args.stdin:
+            if sys.stdin.isatty():
+                raise CliError("Pipe a secret value to --stdin.", exit_code=EXIT_USAGE)
+            value = sys.stdin.read(2049)
+        elif args.from_env:
+            if args.from_env not in os.environ:
+                raise CliError(
+                    "The local secret environment variable is missing.",
+                    code="SECRET_INPUT_MISSING",
+                    exit_code=EXIT_USAGE,
+                )
+            value = os.environ[args.from_env]
+        else:
+            if self.non_interactive:
+                raise CliError(
+                    "Use --stdin or --from-env for non-interactive secret input.",
+                    exit_code=EXIT_USAGE,
+                )
+            value = getpass.getpass("Secret value (hidden): ", stream=sys.stderr)
+        if not value or len(value.encode("utf-8")) > 2048 or "\x00" in value:
+            raise CliError(
+                "Secret value must contain 1–2048 UTF-8 bytes without NUL.",
+                code="INVALID_SECRET_VALUE",
+                exit_code=EXIT_USAGE,
+            )
+        try:
+            return self.client.request(
+                "PUT",
+                f"/workspace/secrets/{identifier(args.name)}",
+                body={"value": value},
+                idempotency_key=self.operation_key(),
+            )
+        finally:
+            value = None
+
+
+def _trusted_delivery_url(url):
+    parsed = urlsplit(url)
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.port not in (None, 443)
+        or parsed.fragment
+        or not parsed.hostname.endswith(".amazonaws.com")
+        or any(ord(char) < 33 for char in url)
+        or "\\" in url
+    ):
+        raise CliError(
+            "Invalid APIZIT artifact delivery endpoint.",
+            code="INVALID_DELIVERY_URL",
+            exit_code=EXIT_NETWORK,
+        )
+
+
+def _download_openapi(url):
+    _trusted_delivery_url(url)
+    session = requests.Session()
+    session.trust_env = False
+    try:
+        with session.get(url, timeout=30, stream=True, allow_redirects=False) as response:
+            if response.status_code != 200:
+                raise ValueError()
+            content = bytearray()
+            for chunk in response.iter_content(64 * 1024):
+                content.extend(chunk)
+                if len(content) > 16 * 1024 * 1024:
+                    raise ValueError()
+            text = content.decode("utf-8-sig")
+            if any(
+                isinstance(token, (yaml.AliasToken, yaml.AnchorToken)) for token in yaml.scan(text)
+            ):
+                raise ValueError()
+            document = yaml.load(text, Loader=_StrictLoader)
+            if not isinstance(document, dict):
+                raise ValueError()
+            json.dumps(document, allow_nan=False)
+            return document
+    except (ValueError, TypeError, yaml.YAMLError, RecursionError, requests.RequestException):
+        raise CliError(
+            "The OpenAPI document could not be downloaded.",
+            code="ARTIFACT_DOWNLOAD_FAILED",
+            exit_code=EXIT_NETWORK,
+        ) from None
+    finally:
+        session.close()