developer-platform-cli 0.1.0__tar.gz

developer_platform_cli-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.pytest_cache/
+__pycache__/
+*.py[cod]

developer_platform_cli-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: developer-platform-cli
+Version: 0.1.0
+Summary: Command-line client for the Developer Platform API
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: rich<14,>=13.9
+Requires-Dist: typer<1,>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: respx<1,>=0.22; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Developer Platform CLI
+
+`devplat` is the command-line client for the Developer Platform API. Its first
+supported workflow is CI-style deployment using a project-scoped deployment
+credential supplied only through environment variables.
+
+Install an editable development copy:
+
+```bash
+python3 -m pip install -e 'platform/cli[dev]'
+```
+
+Set the values returned when the deployment credential was created. Keep the secret
+in the CI system's protected environment and disable shell tracing around this step:
+
+```bash
+export PLATFORM_API_URL=https://platform.example
+export PLATFORM_TOKEN_ENDPOINT=https://identity.example/realms/platform/protocol/openid-connect/token
+export PLATFORM_CLIENT_ID='...'
+export PLATFORM_CLIENT_SECRET='...'
+devplat deploy apply --project hello --file examples/project.json --wait
+```
+
+`PLATFORM_ACCESS_TOKEN` may be used instead of the deployment-credential variables
+for a short-lived, externally obtained token. The CLI never persists either form of
+authentication material.

developer_platform_cli-0.1.0/README.md

@@ -0,0 +1,26 @@
+# Developer Platform CLI
+
+`devplat` is the command-line client for the Developer Platform API. Its first
+supported workflow is CI-style deployment using a project-scoped deployment
+credential supplied only through environment variables.
+
+Install an editable development copy:
+
+```bash
+python3 -m pip install -e 'platform/cli[dev]'
+```
+
+Set the values returned when the deployment credential was created. Keep the secret
+in the CI system's protected environment and disable shell tracing around this step:
+
+```bash
+export PLATFORM_API_URL=https://platform.example
+export PLATFORM_TOKEN_ENDPOINT=https://identity.example/realms/platform/protocol/openid-connect/token
+export PLATFORM_CLIENT_ID='...'
+export PLATFORM_CLIENT_SECRET='...'
+devplat deploy apply --project hello --file examples/project.json --wait
+```
+
+`PLATFORM_ACCESS_TOKEN` may be used instead of the deployment-credential variables
+for a short-lived, externally obtained token. The CLI never persists either form of
+authentication material.

developer_platform_cli-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "developer-platform-cli"
+version = "0.1.0"
+description = "Command-line client for the Developer Platform API"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "httpx>=0.28,<1",
+  "pydantic>=2.10,<3",
+  "rich>=13.9,<14",
+  "typer>=0.15,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3,<9",
+  "respx>=0.22,<1",
+]
+
+[project.scripts]
+devplat = "platform_cli.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/platform_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

developer_platform_cli-0.1.0/src/platform_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Developer Platform command-line client."""
+
+__version__ = "0.1.0"

developer_platform_cli-0.1.0/src/platform_cli/__main__.py

@@ -0,0 +1,128 @@
+"""The devplat executable."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import sys
+import time
+from typing import Annotated
+
+import typer
+
+from .client import OperationFailed, OperationTimeout, PlatformClient, wait_for_operation
+from .config import ConfigurationError, authentication_source, runtime_config
+from .errors import ApiError
+from .models import OperationStatus, application_body
+
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="Developer Platform command-line client.")
+deploy_app = typer.Typer(no_args_is_help=True, help="Deploy versioned application specifications.")
+auth_app = typer.Typer(no_args_is_help=True, help="Inspect the active non-persistent authentication source.")
+app.add_typer(deploy_app, name="deploy")
+app.add_typer(auth_app, name="auth")
+
+
+def _read_json(path: str) -> dict[str, object]:
+    try:
+        contents = sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8")
+        return application_body(json.loads(contents))
+    except (OSError, json.JSONDecodeError, ValueError) as error:
+        raise typer.BadParameter(f"unable to read a JSON application specification: {error}", param_hint="--file") from error
+
+
+def _emit(value: object, output: str) -> None:
+    if output == "json":
+        typer.echo(json.dumps(value, separators=(",", ":"), default=str))
+        return
+    if isinstance(value, dict) and "operation_id" in value:
+        typer.echo(f"Operation {value['operation_id']} is {value.get('state', 'unknown')} (revision {value.get('revision', 'unknown')}).")
+        return
+    typer.echo(str(value))
+
+
+def _failure(error: Exception, output: str) -> typer.Exit:
+    if isinstance(error, ApiError):
+        payload = {"status": error.status_code, "detail": error.detail, "code": error.code, "request_id": error.request_id}
+        if output == "json":
+            typer.echo(json.dumps(payload, separators=(",", ":")), err=True)
+        else:
+            typer.echo(error.detail, err=True)
+        return typer.Exit(error.exit_code)
+    if isinstance(error, ConfigurationError):
+        typer.echo(str(error), err=True)
+        return typer.Exit(2)
+    if isinstance(error, OperationFailed):
+        typer.echo(f"Operation {error.status.operation_id} failed: {error}", err=True)
+        return typer.Exit(9)
+    if isinstance(error, OperationTimeout):
+        typer.echo(f"{error} Resume with devplat operations watch {error.operation_id} when available.", err=True)
+        return typer.Exit(10)
+    typer.echo(str(error), err=True)
+    return typer.Exit(8)
+
+
+@auth_app.command("status")
+def auth_status(
+    output: Annotated[str, typer.Option("--output", case_sensitive=False)] = "table",
+) -> None:
+    """Show the active authentication source without disclosing credentials."""
+    try:
+        source = authentication_source(runtime_config())
+        _emit({"source": source, "persistent": False}, output)
+    except Exception as error:
+        raise _failure(error, output) from None
+
+
+@deploy_app.command("apply")
+def deploy_apply(
+    project: Annotated[str, typer.Option("--project", min=1, help="Target project name.")],
+    file: Annotated[str, typer.Option("--file", help="JSON specification file, or - for stdin.")],
+    wait: Annotated[bool, typer.Option("--wait", help="Wait for durable operation success and readiness.")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", min=1.0, help="Maximum wait time in seconds.")] = 300.0,
+    poll_interval: Annotated[float, typer.Option("--poll-interval", min=0.1, help="Operation poll interval in seconds.")] = 2.0,
+    if_match: Annotated[str | None, typer.Option("--if-match", help="Expected current revision.")] = None,
+    output: Annotated[str, typer.Option("--output", case_sensitive=False)] = "table",
+) -> None:
+    """Apply one JSON application specification using environment authentication."""
+    if output not in {"table", "json", "plain"}:
+        raise typer.BadParameter("must be table, json, or plain", param_hint="--output")
+    try:
+        body = _read_json(file)
+        config = runtime_config()
+        client = PlatformClient(config)
+        try:
+            token = client.access_token()
+            accepted = client.deploy(project, body, token, if_match)
+            if not wait:
+                _emit(accepted.model_dump(), output)
+                return
+
+            def update(status: OperationStatus) -> None:
+                if output != "json":
+                    typer.echo(
+                        f"Operation {status.operation_id}: {status.state}; readiness {status.readiness.state}.",
+                        err=True,
+                    )
+
+            completed = wait_for_operation(
+                client, accepted, token, timeout, poll_interval, time.monotonic, time.sleep, update
+            )
+            _emit(completed.model_dump(), output)
+        finally:
+            client.close()
+    except typer.BadParameter:
+        raise
+    except KeyboardInterrupt:
+        typer.echo("Waiting interrupted; the durable platform operation continues.", err=True)
+        raise typer.Exit(10) from None
+    except Exception as error:
+        raise _failure(error, output) from None
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

developer_platform_cli-0.1.0/src/platform_cli/client.py

@@ -0,0 +1,127 @@
+"""HTTP and OIDC client boundary for deployment credentials."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+from pydantic import ValidationError
+
+from .config import DeploymentCredentialAuth, RuntimeConfig, authentication_source
+from .errors import ApiError, safe_error_body
+from .models import OperationAccepted, OperationStatus, TokenResponse
+
+
+class PlatformClient:
+    def __init__(self, config: RuntimeConfig, http_client: httpx.Client | None = None):
+        self.config = config
+        self._http = http_client or httpx.Client(timeout=httpx.Timeout(30.0), verify=config.ca_bundle or True)
+        self._owns_http = http_client is None
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def access_token(self) -> str:
+        source = authentication_source(self.config)
+        if source == "access-token-environment":
+            assert self.config.access_token_auth is not None
+            return self.config.access_token_auth.access_token
+        assert self.config.deployment_credential_auth is not None
+        return self._client_credentials_token(self.config.deployment_credential_auth)
+
+    def deploy(self, project: str, body: dict[str, Any], access_token: str, if_match: str | None = None) -> OperationAccepted:
+        headers = {"Authorization": f"Bearer {access_token}"}
+        if if_match is not None:
+            headers["If-Match"] = if_match
+        response = self._request("PUT", f"/projects/{project}", headers=headers, json=body)
+        try:
+            return OperationAccepted.model_validate(response.json())
+        except (ValidationError, ValueError) as error:
+            raise RuntimeError("The platform returned an invalid deployment operation.") from error
+
+    def operation(self, status_url: str, access_token: str) -> OperationStatus:
+        if not status_url.startswith("/") or status_url.startswith("//"):
+            raise RuntimeError("The platform returned an unsafe operation status URL.")
+        response = self._request("GET", status_url, headers={"Authorization": f"Bearer {access_token}"})
+        try:
+            return OperationStatus.model_validate(response.json())
+        except (ValidationError, ValueError) as error:
+            raise RuntimeError("The platform returned an invalid operation status.") from error
+
+    def _client_credentials_token(self, credential: DeploymentCredentialAuth) -> str:
+        try:
+            response = self._http.post(
+                credential.token_endpoint,
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": credential.client_id,
+                    "client_secret": credential.client_secret,
+                },
+            )
+        except httpx.HTTPError as error:
+            raise RuntimeError("Unable to reach the OIDC token endpoint.") from error
+        self._raise_for_error(response)
+        try:
+            token = TokenResponse.model_validate(response.json())
+        except (ValidationError, ValueError) as error:
+            raise RuntimeError("The OIDC provider returned an invalid token response.") from error
+        if token.token_type.casefold() != "bearer":
+            raise RuntimeError("The OIDC provider returned an unsupported token type.")
+        return token.access_token
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        try:
+            response = self._http.request(method, self.config.api_url + path, **kwargs)
+        except httpx.HTTPError as error:
+            raise RuntimeError("Unable to reach the Platform API.") from error
+        self._raise_for_error(response)
+        return response
+
+    @staticmethod
+    def _raise_for_error(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            detail, code = safe_error_body(response.json())
+        except ValueError:
+            detail, code = "The platform returned an error without a safe detail.", None
+        request_id = response.headers.get("x-request-id") or response.headers.get("x-correlation-id")
+        raise ApiError(response.status_code, detail, code, request_id)
+
+
+def wait_for_operation(
+    client: PlatformClient,
+    accepted: OperationAccepted,
+    access_token: str,
+    timeout_seconds: float,
+    interval_seconds: float,
+    clock: Callable[[], float],
+    sleep: Callable[[float], None],
+    on_update: Callable[[OperationStatus], None],
+) -> OperationStatus:
+    """Wait for apply success and live readiness without cancelling a durable operation."""
+    deadline = clock() + timeout_seconds
+    while True:
+        status = client.operation(accepted.status_url, access_token)
+        on_update(status)
+        if status.state in {"failed", "cancelled"}:
+            raise OperationFailed(status)
+        if status.state == "succeeded" and status.readiness.state == "ready":
+            return status
+        if clock() >= deadline:
+            raise OperationTimeout(accepted.operation_id)
+        sleep(interval_seconds)
+
+
+class OperationFailed(RuntimeError):
+    def __init__(self, status: OperationStatus):
+        super().__init__(status.error_code or "The platform operation failed.")
+        self.status = status
+
+
+class OperationTimeout(TimeoutError):
+    def __init__(self, operation_id: str):
+        super().__init__(f"Timed out while waiting for operation {operation_id}.")
+        self.operation_id = operation_id

developer_platform_cli-0.1.0/src/platform_cli/config.py

@@ -0,0 +1,81 @@
+"""Non-persistent authentication configuration for the first CLI increment."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+
+
+class ConfigurationError(ValueError):
+    """Raised when CLI authentication environment is incomplete or invalid."""
+
+
+@dataclass(frozen=True)
+class AccessTokenAuth:
+    access_token: str
+
+
+@dataclass(frozen=True)
+class DeploymentCredentialAuth:
+    token_endpoint: str
+    client_id: str
+    client_secret: str
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    api_url: str
+    ca_bundle: str | None
+    access_token_auth: AccessTokenAuth | None
+    deployment_credential_auth: DeploymentCredentialAuth | None
+
+
+def runtime_config(environment: dict[str, str] | None = None) -> RuntimeConfig:
+    """Read the non-persistent command configuration from an environment mapping."""
+    env = os.environ if environment is None else environment
+    api_url = env.get("PLATFORM_API_URL", "").rstrip("/")
+    if not api_url:
+        raise ConfigurationError("PLATFORM_API_URL is required")
+
+    token = env.get("PLATFORM_ACCESS_TOKEN")
+    if token:
+        return RuntimeConfig(
+            api_url=api_url,
+            ca_bundle=env.get("PLATFORM_CA_BUNDLE") or None,
+            access_token_auth=AccessTokenAuth(token),
+            deployment_credential_auth=None,
+        )
+
+    credential_values = {
+        "PLATFORM_TOKEN_ENDPOINT": env.get("PLATFORM_TOKEN_ENDPOINT"),
+        "PLATFORM_CLIENT_ID": env.get("PLATFORM_CLIENT_ID"),
+        "PLATFORM_CLIENT_SECRET": env.get("PLATFORM_CLIENT_SECRET"),
+    }
+    present = {name for name, value in credential_values.items() if value}
+    if present and len(present) != len(credential_values):
+        missing = sorted(set(credential_values) - present)
+        raise ConfigurationError("deployment credential environment is incomplete; missing " + ", ".join(missing))
+
+    credential = None
+    if len(present) == len(credential_values):
+        credential = DeploymentCredentialAuth(
+            token_endpoint=credential_values["PLATFORM_TOKEN_ENDPOINT"] or "",
+            client_id=credential_values["PLATFORM_CLIENT_ID"] or "",
+            client_secret=credential_values["PLATFORM_CLIENT_SECRET"] or "",
+        )
+    return RuntimeConfig(
+        api_url=api_url,
+        ca_bundle=env.get("PLATFORM_CA_BUNDLE") or None,
+        access_token_auth=None,
+        deployment_credential_auth=credential,
+    )
+
+
+def authentication_source(config: RuntimeConfig) -> str:
+    if config.access_token_auth is not None:
+        return "access-token-environment"
+    if config.deployment_credential_auth is not None:
+        return "deployment-credential-environment"
+    raise ConfigurationError(
+        "set PLATFORM_ACCESS_TOKEN or PLATFORM_TOKEN_ENDPOINT, PLATFORM_CLIENT_ID, and PLATFORM_CLIENT_SECRET"
+    )

developer_platform_cli-0.1.0/src/platform_cli/errors.py

@@ -0,0 +1,45 @@
+"""Safe API error mapping and stable command exit codes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ApiError(Exception):
+    status_code: int
+    detail: str
+    code: str | None = None
+    request_id: str | None = None
+
+    @property
+    def exit_code(self) -> int:
+        return exit_code_for_status(self.status_code)
+
+
+def exit_code_for_status(status_code: int) -> int:
+    if status_code in {401}:
+        return 3
+    if status_code == 403:
+        return 4
+    if status_code == 404:
+        return 5
+    if status_code == 409:
+        return 6
+    if status_code in {400, 422}:
+        return 7
+    if status_code == 429 or status_code >= 500:
+        return 8
+    return 8
+
+
+def safe_error_body(value: Any) -> tuple[str, str | None]:
+    if not isinstance(value, dict):
+        return "The platform returned an error without a safe detail.", None
+    detail = value.get("detail")
+    code = value.get("code")
+    return (
+        detail if isinstance(detail, str) else "The platform returned an error without a safe detail.",
+        code if isinstance(code, str) else None,
+    )

developer_platform_cli-0.1.0/src/platform_cli/models.py

@@ -0,0 +1,46 @@
+"""Strict boundary models for the first deployment workflow."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TokenResponse(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    access_token: str = Field(min_length=1)
+    token_type: str = Field(min_length=1)
+
+
+class OperationAccepted(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    operation_id: str = Field(min_length=1)
+    state: str = Field(min_length=1)
+    revision: int = Field(ge=0)
+    status_url: str = Field(min_length=1)
+
+
+class Readiness(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    state: str = Field(min_length=1)
+    reason: str | None = None
+
+
+class OperationStatus(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    operation_id: str = Field(min_length=1)
+    state: str = Field(min_length=1)
+    revision: int = Field(ge=0)
+    error_code: str | None = None
+    readiness: Readiness
+
+
+def application_body(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValueError("application specification must be a JSON object")
+    return value

developer_platform_cli-0.1.0/tests/test_client.py

@@ -0,0 +1,54 @@
+import httpx
+
+from platform_cli.client import PlatformClient, wait_for_operation
+from platform_cli.config import runtime_config
+from platform_cli.models import OperationAccepted
+
+
+def test_deployment_credential_exchange_and_apply_use_bearer_token():
+    requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.host == "identity.example":
+            return httpx.Response(200, json={"access_token": "short-lived", "token_type": "Bearer"})
+        return httpx.Response(202, json={
+            "operation_id": "operation-1", "state": "queued", "revision": 1, "status_url": "/v1/operations/operation-1",
+        })
+
+    config = runtime_config({
+        "PLATFORM_API_URL": "https://platform.example",
+        "PLATFORM_TOKEN_ENDPOINT": "https://identity.example/token",
+        "PLATFORM_CLIENT_ID": "client-id",
+        "PLATFORM_CLIENT_SECRET": "client-secret",
+    })
+    client = PlatformClient(config, httpx.Client(transport=httpx.MockTransport(handler)))
+
+    token = client.access_token()
+    accepted = client.deploy("smoke", {"name": "smoke", "image": "example/image:1"}, token)
+
+    assert accepted.operation_id == "operation-1"
+    assert requests[0].url == "https://identity.example/token"
+    assert requests[1].headers["authorization"] == "Bearer short-lived"
+
+
+def test_wait_requires_apply_success_and_readiness():
+    responses = iter([
+        {"operation_id": "operation-1", "revision": 1, "state": "running", "error_code": None, "readiness": {"state": "progressing", "reason": "pods_not_ready"}},
+        {"operation_id": "operation-1", "revision": 1, "state": "succeeded", "error_code": None, "readiness": {"state": "ready", "reason": None}},
+    ])
+
+    class FakeClient:
+        def operation(self, _url: str, _token: str):
+            from platform_cli.models import OperationStatus
+            return OperationStatus.model_validate(next(responses))
+
+    ticks = iter([0.0, 0.0, 1.0])
+    updates = []
+    completed = wait_for_operation(
+        FakeClient(), OperationAccepted(operation_id="operation-1", state="queued", revision=1, status_url="/v1/operations/operation-1"),
+        "token", 10.0, 1.0, lambda: next(ticks), lambda _seconds: None, updates.append,
+    )
+
+    assert completed.readiness.state == "ready"
+    assert len(updates) == 2

developer_platform_cli-0.1.0/tests/test_commands.py

@@ -0,0 +1,16 @@
+import json
+
+from typer.testing import CliRunner
+
+from platform_cli.__main__ import app
+
+
+def test_auth_status_reports_environment_source_without_token(monkeypatch):
+    monkeypatch.setenv("PLATFORM_API_URL", "https://platform.example")
+    monkeypatch.setenv("PLATFORM_ACCESS_TOKEN", "should-not-appear")
+
+    result = CliRunner().invoke(app, ["auth", "status", "--output", "json"])
+
+    assert result.exit_code == 0
+    assert json.loads(result.stdout) == {"source": "access-token-environment", "persistent": False}
+    assert "should-not-appear" not in result.output

developer_platform_cli-0.1.0/tests/test_config.py

@@ -0,0 +1,32 @@
+from platform_cli.config import ConfigurationError, authentication_source, runtime_config
+
+
+def test_deployment_credential_environment_is_selected():
+    config = runtime_config({
+        "PLATFORM_API_URL": "https://platform.example/",
+        "PLATFORM_TOKEN_ENDPOINT": "https://identity.example/token",
+        "PLATFORM_CLIENT_ID": "client-id",
+        "PLATFORM_CLIENT_SECRET": "client-secret",
+    })
+
+    assert config.api_url == "https://platform.example"
+    assert authentication_source(config) == "deployment-credential-environment"
+
+
+def test_partial_deployment_credential_environment_fails_closed():
+    try:
+        runtime_config({"PLATFORM_API_URL": "https://platform.example", "PLATFORM_CLIENT_ID": "client-id"})
+    except ConfigurationError as error:
+        assert "PLATFORM_CLIENT_SECRET" in str(error)
+    else:
+        raise AssertionError("expected incomplete credential environment to fail")
+
+
+def test_access_token_takes_precedence_over_an_incomplete_credential_environment():
+    config = runtime_config({
+        "PLATFORM_API_URL": "https://platform.example",
+        "PLATFORM_ACCESS_TOKEN": "access-token",
+        "PLATFORM_CLIENT_ID": "client-id",
+    })
+
+    assert authentication_source(config) == "access-token-environment"