mozbridge-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{mozbridge_cli-0.2.0 → mozbridge_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mozbridge-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: Command-line client for the Mozbridge deployment platform: SSO login, build, publish, status, and rollback for any project hosted on Mozbridge.
 Project-URL: Homepage, https://mozbridge.com
 Project-URL: Documentation, https://github.com/jessin01/mozbridge/blob/main/cli/docs/commands.md

{mozbridge_cli-0.2.0 → mozbridge_cli-0.2.1}/docs/commands.md

@@ -547,6 +547,196 @@ Rollback triggered (task_id=777).
 
 ---
 
+## `mozbridge deploy`
+
+Deploys an already-built image tag to the linked Mozbridge project. A real,
+consequential production action — same category as `mozbridge rollback`: it
+mutates production the moment it's called, **not a dry-run**. Prompts for
+confirmation unless `--yes` is given.
+
+**Flags**:
+| Flag | Meaning |
+|---|---|
+| `--frontend TAG` | Frontend image tag to deploy. |
+| `--backend TAG` | Backend image tag to deploy. |
+| `--env NAME` | Environment to deploy to. Default `prod`. |
+| `--force` | Override a blocking preflight check. Never set automatically — a separate, explicit decision each time. |
+| `--yes` | Skip the interactive confirmation prompt. |
+
+**Requires**: link + login, same as `publish`/`status`/`rollback`. At least
+one of `--frontend`/`--backend` must be given — deploying neither makes no
+sense.
+
+**What it does**: prints what it's about to do (project, which service(s),
+which tag(s), which environment), then either aborts on a declined prompt or
+calls `POST /api/v1/projects/{project_id}/deploy` with
+`{frontend_version, backend_version, services, environment, force}`.
+**`services` is built from which of `--frontend`/`--backend` you actually
+gave a tag** — not the API's own default of deploying both — so the CLI only
+ever asks the platform to deploy what you specified.
+
+The backend runs a preflight check before enqueuing the deploy. A 409
+response means it found a real, known-to-fail condition and refused —
+each blocking check is printed with its title, detail, and suggested
+action, followed by a hint to re-run with `--force` if you want to override
+it. **The CLI never retries with `--force` automatically** — that is always
+a separate, explicit re-invocation.
+
+**Example (`--yes`, single service)**:
+```
+$ mozbridge deploy --backend v1.9.319 --yes
+This will deploy acme/web-app (prod):
+  backend  -> v1.9.319
+Deploy triggered (task_id=888).
+Run `mozbridge logs` to watch it.
+```
+
+**Example (preflight blocked)**:
+```
+$ mozbridge deploy --backend v1.9.319 --yes
+This will deploy acme/web-app (prod):
+  backend  -> v1.9.319
+Preflight failed — this deploy is known to fail.
+  - No registry credential: GHCR_TOKEN is not configured for this project.
+    action: Set a registry credential in Project Settings.
+Pass force=true to deploy anyway.
+Re-run with --force to override — this is not done automatically.
+```
+
+**Failure modes**:
+- Neither `--frontend` nor `--backend` given: clear error, exit 1, no API
+  call is made.
+- Not linked / not logged in: identical messages to `publish` above, exit 1.
+- Confirmation prompt declined (`--yes` not passed, answer is not `y`):
+  Typer's own `Abort` handling — the command exits non-zero without calling
+  the API.
+- Preflight-blocked (409, structured body): every blocking check printed
+  clearly plus a `--force` hint, exit 1 — no automatic retry.
+- Any other API error: the raw `ApiError` message, exit 1.
+
+---
+
+## `mozbridge logs`
+
+Shows **BUILD/DEPLOY OPERATION logs** for the linked project — the log
+output of a Mozbridge build or deploy task (what `publish`, `deploy`, and
+`rollback` trigger). **This is not your running application's
+runtime/request logs** — the platform does not expose those via any API
+today, and this command is not `docker logs` for your live app.
+
+**Flags**:
+| Flag | Meaning |
+|---|---|
+| `TASK_ID` (argument, optional) | Task id of a build/deploy operation. Omit to use the most recent one for this project. |
+| `--follow` / `-f` | Stream new log output as it arrives; exits when the run finishes. |
+
+**Requires**: link + login, same as `status`/`diff`/`rollback`.
+
+**What it does**:
+- If `TASK_ID` is omitted: `GET /api/v1/projects/{project_id}/operations?limit=1`
+  (newest-first, same ordering `status`/`diff` already rely on for
+  deployments) to resolve the most recent operation's `task_id`.
+- Without `--follow`: one `GET /api/v1/projects/operations/{task_id}` call,
+  printing whatever is in `result.logs` right now — a single snapshot, no
+  long-lived connection.
+- With `--follow`: opens `GET /api/v1/projects/operations/{task_id}/stream`
+  (SSE) and prints each `log` event's content as it's parsed. The server
+  closes the stream itself once the operation reaches a terminal state
+  (success/failed/error) — the CLI exits cleanly at that point. A dropped
+  connection surfaces a clear error instead of hanging.
+
+**Example (snapshot)**:
+```
+$ mozbridge logs task-123
+Step 1/5 : FROM python:3.12
+Step 2/5 : COPY . /app
+```
+
+**Example (follow)**:
+```
+$ mozbridge logs task-123 --follow
+Step 1/5 : FROM python:3.12
+Step 2/5 : COPY . /app
+Successfully built abc123
+```
+
+**Failure modes**:
+- Not linked / not logged in: identical messages to `publish` above, exit 1.
+- No `TASK_ID` given and the project has no operations yet: `No operations
+  found for this project yet.`, exit 1.
+- The operation lookup or stream request fails: the raw `ApiError` message
+  (snapshot mode) or `Log stream connection dropped: <error>` (`--follow`),
+  exit 1.
+
+---
+
+## `mozbridge env list` / `mozbridge env set` / `mozbridge env rm`
+
+Manages the linked project's environment variables
+(`GET`/`POST`/`DELETE /api/v1/projects/{project_id}/env-vars[...]`).
+`EnvVar` is a plain `{key, value}` pair — distinct from the project's
+separate Vault-backed secrets blocks — and nothing in the platform's own
+dashboard UI masks these values, so `env list` prints them in plain text.
+
+**Requires**: link + login, same as `status`/`diff`/`rollback`.
+
+### `mozbridge env list`
+
+**Flags**: none.
+
+**What it does**: `GET /api/v1/projects/{project_id}/env-vars`, prints every
+key/value pair sorted by key. Prints `No environment variables set.` if
+there are none.
+
+```
+$ mozbridge env list
+  DATABASE_URL  postgres://user:pass@host/db
+  DEBUG         false
+```
+
+### `mozbridge env set KEY VALUE`
+
+**What it does**: `POST /api/v1/projects/{project_id}/env-vars` with body
+`{"key": KEY, "value": VALUE}`. **This is an upsert, not create-only** —
+read directly off `backend/app/security.py:store_project_env_var`: the
+handler loads the existing key->value dict out of Vault, does
+`existing[key] = value`, and writes the whole dict back. Setting an
+already-existing `KEY` silently overwrites it; there is no 409/400 and no
+separate create-vs-update codepath.
+
+The confirmation deliberately prints only the key, never the value, so a
+secret-shaped `VALUE` isn't echoed a second time into your terminal beyond
+the command invocation itself:
+
+```
+$ mozbridge env set DATABASE_URL postgres://user:pass@host/db
+Set DATABASE_URL.
+```
+
+### `mozbridge env rm KEY`
+
+**What it does**: `DELETE /api/v1/projects/{project_id}/env-vars/{KEY}`.
+**This is idempotent, not a strict "must exist" delete** — read directly
+off `backend/app/security.py:delete_project_env_var`: it deletes `KEY`
+`if key in existing`, and otherwise falls straight through to `return
+True` — either way the route responds 200. Removing a `KEY` that was never
+set still reports success; there is no 404 for a missing key, and this
+command does not invent one.
+
+```
+$ mozbridge env rm DATABASE_URL
+Removed DATABASE_URL.
+```
+
+**Failure modes (all three)**:
+- Not linked / not logged in: identical messages to `publish` above, exit 1.
+- Any other API error (e.g. a 500 from a Vault write/delete failure): the
+  raw `ApiError` message (`Could not list env vars: <detail>` / `Could not
+  set the env var: <detail>` / `Could not remove the env var: <detail>`),
+  exit 1.
+
+---
+
 ## A note on authorization for `publish` / `rollback`
 
 Both commands work today because a plain human Logto session token passes

{mozbridge_cli-0.2.0 → mozbridge_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mozbridge-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "Command-line client for the Mozbridge deployment platform: SSO login, build, publish, status, and rollback for any project hosted on Mozbridge."
 readme = "README.md"
 requires-python = ">=3.10"

{mozbridge_cli-0.2.0 → mozbridge_cli-0.2.1}/src/mozbridge_cli/api.py

@@ -36,6 +36,22 @@ class ApiError(Exception):
     """Raised when the Mozbridge API returns a response we can't recover from."""
 
 
+class PreflightBlockedError(ApiError):
+    """POST .../deploy returned 409 with the structured preflight-blocking body.
+
+    backend/app/features/projects/router.py's `_assert_preflight_clear` shapes
+    this as {message, blocking: [{key, title, detail, action}, ...], override}
+    — distinct enough from every other ApiError (which just carries a flat
+    string `detail`) that callers need the pieces separately to print each
+    blocking check on its own line, not a flattened string.
+    """
+
+    def __init__(self, message: str, blocking: list[dict], override: str | None) -> None:
+        super().__init__(message)
+        self.blocking = blocking
+        self.override = override
+
+
 def _headers(access_token: str, org_id: int | None = None) -> dict[str, str]:
     headers = {"Authorization": f"Bearer {access_token}"}
     if org_id is not None:
@@ -237,6 +253,61 @@ def trigger_build(
     return resp.json()
 
 
+def list_project_env_vars(
+    client: httpx.Client, access_token: str, org_id: int, project_id: int
+) -> list[dict]:
+    """GET /api/v1/projects/{project_id}/env-vars -> list[schemas.EnvVar] ({key, value})."""
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/env-vars"
+    try:
+        resp = client.get(url, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "list env vars")
+    return resp.json()
+
+
+def set_project_env_var(
+    client: httpx.Client, access_token: str, org_id: int, project_id: int, key: str, value: str
+) -> dict:
+    """POST /api/v1/projects/{project_id}/env-vars, body schemas.EnvVarCreate {key, value}.
+
+    This is an upsert, not create-only: router.py's update_project_env_var
+    calls security.store_project_env_var, which reads the existing
+    key->value dict out of Vault, does `existing[key] = value`, and writes
+    the whole dict back. Setting an already-existing key silently
+    overwrites it — there is no separate create-vs-update codepath and no
+    409/400 for an existing key.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/env-vars"
+    try:
+        resp = client.post(url, json={"key": key, "value": value}, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "set the env var")
+    return resp.json()
+
+
+def delete_project_env_var(
+    client: httpx.Client, access_token: str, org_id: int, project_id: int, key: str
+) -> dict:
+    """DELETE /api/v1/projects/{project_id}/env-vars/{key}.
+
+    Idempotent, not a strict "must exist" delete: router.py's
+    delete_project_env_var calls security.delete_project_env_var, which
+    only deletes `key` from the existing dict `if key in existing` and
+    otherwise falls straight through to `return True` — either way the
+    route responds 200 {"status": "success", "message": "Variable <key>
+    removed"}. There is no 404 for a key that was never set.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/env-vars/{key}"
+    try:
+        resp = client.delete(url, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "remove the env var")
+    return resp.json()
+
+
 def trigger_prebuilt_build(
     client: httpx.Client,
     access_token: str,
@@ -272,3 +343,94 @@ def trigger_prebuilt_build(
         raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
     _raise_for_status(resp, "register the prebuilt image")
     return resp.json()
+
+
+def deploy_project(
+    client: httpx.Client, access_token: str, org_id: int, project_id: int, payload: dict
+) -> dict:
+    """POST /api/v1/projects/{project_id}/deploy, body schemas.DeployRequest.
+
+    `payload` is sent as-is — the caller (main.py's `deploy` command) builds
+    the exact DeployRequest-shaped dict, since it's the one that knows which
+    fields the human actually asked for.
+
+    A 409 here means the backend's preflight gate (`_assert_preflight_clear`)
+    found real, known-to-fail conditions and refused to enqueue the deploy —
+    handled as `PreflightBlockedError`, not folded into the generic ApiError
+    path below, so the caller can print each blocking check individually.
+    Any other non-2xx (network error, plain validation error, etc.) falls
+    through to the same `_raise_for_status` -> `ApiError` path every other
+    function in this module uses.
+
+    Returns {"status": "enqueued", "action": "deploy", "task_id": ..., ...deploy_kwargs}.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/deploy"
+    try:
+        resp = client.post(url, json=payload, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+
+    if resp.status_code == 409:
+        try:
+            body = resp.json()
+        except ValueError:
+            body = None
+        detail = body.get("detail") if isinstance(body, dict) else None
+        if isinstance(detail, dict) and "blocking" in detail:
+            raise PreflightBlockedError(
+                detail.get("message") or "Preflight failed — this deploy is known to fail.",
+                detail.get("blocking") or [],
+                detail.get("override"),
+            )
+
+    _raise_for_status(resp, "deploy the project")
+    return resp.json()
+
+
+def list_project_operations(
+    client: httpx.Client, access_token: str, org_id: int, project_id: int, *, limit: int = 1
+) -> list[dict]:
+    """GET /api/v1/projects/{project_id}/operations?limit=... -> list[schemas.ProjectOperation].
+
+    Backend orders these newest-first (ProjectService.get_operations_with_logs
+    sorts by created_at.desc(), same pattern as list_project_deployments), so
+    `limit=1` is enough to resolve "the most recent operation for this
+    project" for `mozbridge logs` when no task id is given.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/operations"
+    try:
+        resp = client.get(url, params={"limit": limit}, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "list operations")
+    return resp.json()
+
+
+def get_operation(client: httpx.Client, access_token: str, org_id: int, task_id: str) -> dict:
+    """GET /api/v1/projects/operations/{task_id} -> schemas.ProjectOperation.
+
+    Note this route lives directly under /operations/, not
+    /{project_id}/operations/{task_id} — router.py's `get_task_operation`
+    resolves the project purely from the ProjectOperation row itself (scoped
+    by org via X-Organization-Id), so no project_id is needed in the path.
+    Used by `mozbridge logs` (without --follow) for a one-shot snapshot of
+    whatever's in `result.logs` so far.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/operations/{task_id}"
+    try:
+        resp = client.get(url, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "fetch the operation")
+    return resp.json()
+
+
+def operation_stream_url(task_id: str) -> str:
+    """URL for GET /api/v1/projects/operations/{task_id}/stream (SSE).
+
+    A plain string builder, not a request function — `mozbridge logs
+    --follow` needs the URL to open its own long-lived `client.stream(...)`
+    call directly (see main.py's `_iter_sse_events`), rather than going
+    through a request/response helper shaped for ordinary JSON calls.
+    """
+    return f"{config.API_BASE_URL}{config.PROJECTS_PATH}/operations/{task_id}/stream"