mozbridge-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{mozbridge_cli-0.3.0 → mozbridge_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mozbridge-cli
-Version: 0.3.0
+Version: 0.4.0
 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
@@ -250,11 +250,13 @@ written, or permission-checked in this path at all. Because of that,
 means "don't attempt an interactive login") — unset it first if you actually
 want to run the device flow.
 
-**Where the token comes from**: a project-scoped Mozbridge `ServiceToken`,
-created out of band via the Mozbridge dashboard/API
-(`create_service_token`) — the CLI never creates or mints one itself. Set it
-as your CI platform's secret store, never as a `--token` flag (it would leak
-into shell history and process listings) and never committed to the repo.
+**Where the token comes from**: a project- or org-scoped Mozbridge
+`ServiceToken`. Mint one directly from this CLI — `mozbridge token create
+--scope deploy` (requires an active `mozbridge login` session; see
+`mozbridge token create --help`) — or out of band via the dashboard/API
+(`create_service_token`). Set it as your CI platform's secret store, never
+as a `--token` flag (it would leak into shell history and process
+listings) and never committed to the repo.
 
 **`MOZBRIDGE_TOKEN` vs `MOZBRIDGE_BUILD_TOKEN` — do not confuse these**:
 

{mozbridge_cli-0.3.0 → mozbridge_cli-0.4.0}/README.md

@@ -222,11 +222,13 @@ written, or permission-checked in this path at all. Because of that,
 means "don't attempt an interactive login") — unset it first if you actually
 want to run the device flow.
 
-**Where the token comes from**: a project-scoped Mozbridge `ServiceToken`,
-created out of band via the Mozbridge dashboard/API
-(`create_service_token`) — the CLI never creates or mints one itself. Set it
-as your CI platform's secret store, never as a `--token` flag (it would leak
-into shell history and process listings) and never committed to the repo.
+**Where the token comes from**: a project- or org-scoped Mozbridge
+`ServiceToken`. Mint one directly from this CLI — `mozbridge token create
+--scope deploy` (requires an active `mozbridge login` session; see
+`mozbridge token create --help`) — or out of band via the dashboard/API
+(`create_service_token`). Set it as your CI platform's secret store, never
+as a `--token` flag (it would leak into shell history and process
+listings) and never committed to the repo.
 
 **`MOZBRIDGE_TOKEN` vs `MOZBRIDGE_BUILD_TOKEN` — do not confuse these**:
 

{mozbridge_cli-0.3.0 → mozbridge_cli-0.4.0}/docs/commands.md

@@ -575,12 +575,25 @@ calls `POST /api/v1/projects/{project_id}/deploy` with
 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.
+Before the confirmation prompt, `deploy` also proactively calls `GET
+/projects/{id}/preflight` (the platform's own pre-deploy checks) and
+prints anything at `warn`/`fail` level — title, detail, and suggested
+action — so a likely-to-fail condition is visible before you commit, not
+just after a 409. When every check is `pass`, nothing extra is printed —
+the happy path stays exactly as quiet as before this existed. A failed
+lookup here (network error, etc.) is swallowed silently and never blocks
+`deploy` — this is informational only, matching the backend's own
+fail-open design; the real gate is still the backend's own check at
+enqueue time. These checks are platform-level (registry credentials, DNS,
+disk, Vault role, and similar) — they do **not** detect a project's own
+compose/template misconfiguration.
+
+The backend also runs its own 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)**:
 ```
@@ -737,6 +750,201 @@ Removed DATABASE_URL.
 
 ---
 
+## `mozbridge registry status` / `mozbridge registry set`
+
+Manages the linked project's own container-registry credential, used by
+`publish --local` builds and by platform-side deploys when no
+platform-provisioned registry applies. GET never returns a token/secret
+value — `schemas.RegistryCredentialStatus` has no such field — so there is
+no `registry get` that prints one.
+
+### `mozbridge registry status`
+
+**What it does**: `GET /api/v1/projects/{project_id}/registry`. If the
+project has its own credential configured, prints it (`registry_url`,
+`username`, `updated_at`) and stops — a project-level credential always
+takes precedence. Only when the project has none does it also call `GET
+/api/v1/organizations/{org_id}/registry` and report the org-level default
+instead, since that's what a build/deploy will actually fall back to.
+This mirrors the real resolution order
+(`app/services/registry_credentials.resolve_registry_credential`: project
+override → org default → none) rather than only ever showing the
+project's own (possibly misleading) empty state.
+
+```
+$ mozbridge registry status
+No project-level registry credential configured.
+Builds/deploys will use the ORG-level default:
+  registry_url: ghcr.io
+  username:     acme-bot
+  updated_at:   2026-09-01T12:00:00Z
+```
+
+If neither is configured:
+
+```
+$ mozbridge registry status
+No registry credential configured at the project or org level.
+`--local` builds will fail without one — run `mozbridge registry set`.
+```
+
+### `mozbridge registry set`
+
+**Flags**: `--url` (default `ghcr.io`), `--username` (required), `--token`
+(required — the registry password/token, not a Mozbridge service token).
+
+**What it does**: `PUT /api/v1/projects/{project_id}/registry`. Always
+writes the **project-level** credential — there is no `--org` flag on this
+command, so an org-level default is configured from the dashboard
+(**Organization Settings → Container Registry**), not from here. The
+backend validates the credential against the real registry before storing
+it; a bad credential is rejected with the registry's own error, not
+silently saved.
+
+```
+$ mozbridge registry set --url ghcr.io --username acme-bot --token ghp_xxx
+Registry credential set (ghcr.io, username=acme-bot).
+```
+
+**Failure modes**: not linked / not logged in, exit 1. Registry rejects
+the credential (bad token, wrong URL): the raw validation error, exit 1.
+
+---
+
+## `mozbridge secrets list` / `mozbridge secrets set`
+
+Manages the linked project's Vault-backed, per-environment/per-component
+secrets (`backend/app/features/projects/router.py`'s
+`/environments/{env}/secrets/{component}` routes) — distinct from the
+plain env-vars `env` wraps. The underlying replace-all POST endpoint
+deletes any key not included in the request; this CLI deliberately never
+calls it — `secrets set` uses PATCH (merge one key) only, and `api.py` has
+no wrapper for the replace-all route at all, so there is nothing here
+that could call it by accident.
+
+### `mozbridge secrets list`
+
+**Flags**: `--component` (`backend` default, or `frontend`/`infra`),
+`--env` (`prod` default), `--show-values` (fetch and print actual VALUES
+instead of just key names — prompts for confirmation unless `--yes` is
+also passed).
+
+**What it does**: defaults to the keys-only endpoint — no secret value
+ever leaves the server for a plain `mozbridge secrets list`. With
+`--show-values`, confirms (real secret material is about to print to your
+terminal and end up in scrollback/history — same gating as `deploy`) then
+fetches and prints actual values.
+
+```
+$ mozbridge secrets list
+backend/prod: 2 secret(s)
+  DATABASE_URL
+  STRIPE_SECRET_KEY
+```
+
+### `mozbridge secrets set KEY VALUE`
+
+**Flags**: `--component` (`backend` default), `--env` (`prod` default).
+
+**What it does**: `PATCH .../secrets/{component}` — merges this one key
+server-side over a strict read of what's already there; never touches any
+other key. There is no `secrets rm` — the backend has no single-key
+delete endpoint, only PATCH-to-add/update or the wholesale-replace POST
+this CLI avoids on purpose. Removing a key today means the dashboard, or
+accepting the replace-all risk directly.
+
+```
+$ mozbridge secrets set STRIPE_SECRET_KEY sk_live_xxx
+Set STRIPE_SECRET_KEY (backend/prod).
+```
+
+**Failure modes (both commands)**: not linked / not logged in, exit 1.
+Any other API error: the raw `ApiError` message, exit 1.
+
+---
+
+## `mozbridge token create`
+
+Mints a new Mozbridge `ServiceToken` without leaving the CLI — wraps `POST
+/api/v1/tokens` (`token_router.create_service_token`), authenticated by
+the CLI's existing human login session. A service token cannot call this
+endpoint to mint further tokens (enforced server-side), which is exactly
+why this command requires `mozbridge login`, not `MOZBRIDGE_TOKEN`.
+
+**Flags**:
+| Flag | Meaning |
+|---|---|
+| `--scope` | Repeatable. Required at least once — no silent default. Real scopes: `read`, `write`, `deploy`, `admin`, `build`. |
+| `--name` | Token name. Defaults to a generated `mozbridge-cli-<slug>-<random>` name. |
+| `--org` | Mint an org-scoped token (bound to the linked org, no single project) instead of the default project-scoped one. |
+| `--project` | Mint a project-scoped token — already the default; pass only for explicitness. Mutually exclusive with `--org`. |
+| `--expires` | A single duration: `45m`, `24h`, `30d`, `2w`. Omit for a token that never expires. |
+
+**What it does**: calls `create_service_token` with the given scopes,
+bound to the linked project (default) or org (`--org`). The raw token
+value is printed once, in full — the one place in this CLI where printing
+a real secret to the terminal is correct, since there is no `mozbridge
+token show` to retrieve it again.
+
+```
+$ mozbridge token create --scope build --expires 30d
+Token created: mozbridge-cli-acme-web-app-3f9a2c1e (project-scoped, scopes=build)
+  expires_at: 2026-10-14T12:00:00Z
+
+======================================================================
+SAVE THIS TOKEN NOW — it will never be shown again:
+
+    mbt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+Store it in a password manager or your CI provider's secret store
+immediately. There is no `mozbridge token show` — this is the only time
+the raw value is ever returned.
+======================================================================
+```
+
+**Failure modes**: no `--scope` given: clear error, exit 1, no API call.
+Both `--org` and `--project` given: clear error, exit 1. Invalid
+`--expires` format: clear error naming the expected shape, exit 1. Not
+linked / not logged in: identical messages to `publish` above, exit 1.
+Any other API error: the raw `ApiError` message, exit 1.
+
+---
+
+## `mozbridge doctor`
+
+A self-diagnostic checklist for this CLI's setup — same motivation as
+sibling package `cruxhive-mcp`'s own `cruxhive-doctor`: enough moving
+parts (cached session, per-repo link file, registry credential, optional
+build token, local docker daemon) that "is my setup actually working"
+deserves one command instead of five.
+
+**What it checks, in order**: logged in, linked (verified with a real
+`GET /projects/{id}` call, not just the presence of
+`.mozbridge/link.json`), project-level registry credential configured,
+the platform's own pre-deploy checks (the same `GET .../preflight` call
+`deploy` now runs proactively), whether `MOZBRIDGE_BUILD_TOKEN` is set,
+and whether Docker is available locally. Each check is independent — one
+erroring API call is reported as "could not check (error)" on its own
+line and never prevents the rest from running.
+
+```
+$ mozbridge doctor
+✓ Logged in: session valid
+✓ Linked: acme/web-app (.mozbridge/link.json present) — resolved via API
+○ Registry configured: no project-level registry credential configured (normal, not an error — ...)
+✓ Pre-deploy checks: all clear (runs the platform's own pre-deploy checks)
+○ MOZBRIDGE_BUILD_TOKEN set: not set — only required for `mozbridge publish --local`
+✓ Docker available: docker CLI + daemon reachable
+```
+
+**Exit code**: non-zero only when a MEANINGFUL gate failed — not logged
+in, or not linked. Registry, pre-deploy checks, `MOZBRIDGE_BUILD_TOKEN`,
+and Docker are informational only: none of them are required for every
+workflow this CLI supports, so a "not configured"/"not set"/"not found"
+result never fails the command.
+
+---
+
 ## A note on authorization for `publish` / `rollback`
 
 Both commands work today because a plain human Logto session token passes

{mozbridge_cli-0.3.0 → mozbridge_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mozbridge-cli"
-version = "0.3.0"
+version = "0.4.0"
 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.3.0 → mozbridge_cli-0.4.0}/src/mozbridge_cli/api.py

@@ -324,6 +324,33 @@ def get_project_registry(client: httpx.Client, access_token: str, org_id: int, p
     return resp.json()
 
 
+def get_org_registry(client: httpx.Client, access_token: str, org_id: int) -> dict:
+    """GET /api/v1/organizations/{org_id}/registry -> schemas.RegistryCredentialStatus.
+
+    Same response shape as get_project_registry above — {configured,
+    registry_url, username, updated_at}, token never included
+    (backend/app/features/identity/router.py:521-537's get_org_registry
+    mirrors the project-level route's own never-return-the-token design).
+    This is the org's default registry credential, used as a fallback for
+    any project that has no project-level override — see
+    app/services/registry_credentials.resolve_registry_credential, whose
+    real resolution order is project override -> org default -> none.
+
+    No X-Organization-Id header: get_org_registry is gated by
+    ensure_permify_org_access(user, org_id, db), which takes org_id
+    straight from the path, not from that header — same as
+    list_organizations above, the only other /organizations route this
+    module calls.
+    """
+    url = f"{config.API_BASE_URL}{config.ORGANIZATIONS_PATH}/{org_id}/registry"
+    try:
+        resp = client.get(url, headers=_headers(access_token))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_for_status(resp, "fetch the org registry credential status")
+    return resp.json()
+
+
 def set_project_registry(
     client: httpx.Client,
     access_token: str,
@@ -503,6 +530,47 @@ def deploy_project(
     return resp.json()
 
 
+def get_project_preflight(client: httpx.Client, access_token: str, org_id: int, project_id: int) -> dict:
+    """GET /api/v1/projects/{project_id}/preflight -> preflight.Preflight.as_dict().
+
+    Read-only (backend/app/features/projects/router.py:1534's
+    project_preflight docstring: "nothing here provisions, binds or
+    writes"). Returns:
+
+        {project_id, project_slug, host, can_deploy,
+         blocking: [key, ...], warnings: [key, ...],
+         checks: [{key, level, title, detail, action}, ...]}
+
+    (see backend/app/services/preflight.py's Preflight.as_dict; `level` is
+    one of "pass"/"warn"/"fail", `action` is None when there's nothing to
+    do). `can_deploy` is `not blocking` — exactly the 10 checks
+    run_preflight assembles (placement, host_ready, architecture, dns,
+    registry, disk, vault_role, site_placement, secrets, observability).
+    This is the SAME gate `deploy_project` above already hits reactively as
+    a 409 (`_assert_preflight_clear` calls this same `run_preflight`); this
+    wrapper lets a caller run it proactively, before committing to a
+    deploy, not instead of that reactive path.
+
+    Does not detect a project's compose/template mismatch or any other
+    app-specific misconfiguration — none of the 10 checks cover that class
+    of problem. Callers must not describe this as catching it.
+
+    The backend's own gate fails OPEN: if preflight itself cannot be
+    computed (vault down, host lookup error, etc.), the real deploy is not
+    blocked. This read-only endpoint has no gate to fail open around, but a
+    caller of this wrapper should apply the same philosophy on its own
+    side: treat an ApiError here as "could not check", not as a reason to
+    block anything itself.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/preflight"
+    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, "run pre-deploy checks")
+    return resp.json()
+
+
 def list_project_operations(
     client: httpx.Client, access_token: str, org_id: int, project_id: int, *, limit: int = 1
 ) -> list[dict]:
@@ -541,6 +609,54 @@ def get_operation(client: httpx.Client, access_token: str, org_id: int, task_id:
     return resp.json()
 
 
+def create_service_token(
+    client: httpx.Client,
+    access_token: str,
+    org_id: int,
+    *,
+    name: str,
+    token_type: str,
+    scopes: list[str],
+    project_id: int | None = None,
+    expires_at: str | None = None,
+) -> dict:
+    """POST /api/v1/tokens, body identity.token_router.TokenCreate.
+
+    Authenticated by the caller's regular LOGIN session access_token, never
+    a service token — create_service_token (token_router.py:146) is gated
+    by get_current_user and explicitly rejects a service-token caller (403
+    "Service tokens cannot mint new tokens"), a deliberate anti-escalation
+    design. `org_id` is sent as the X-Organization-Id header for
+    consistency with every other call in this module, though this route
+    does not itself depend on get_current_org: `org_id` in the JSON body
+    only matters for an org-scoped token (the backend 400s without it), and
+    is ignored/overwritten server-side for a project-scoped one
+    (project.organization_id wins over anything the client sends).
+
+    `project_id`/`expires_at` are omitted from the body entirely when None,
+    same "let the backend's own default apply" convention as trigger_build
+    above — expires_at omitted means the token never expires (schemas
+    default), project_id omitted means an org-scoped token.
+
+    Returns TokenCreated: the full token record plus `token`, the raw value
+    — shown exactly once here, never retrievable from the API again.
+    """
+    payload: dict = {"name": name, "type": token_type, "scopes": scopes}
+    if project_id is not None:
+        payload["project_id"] = project_id
+    if token_type == "org":
+        payload["org_id"] = org_id
+    if expires_at is not None:
+        payload["expires_at"] = expires_at
+    url = f"{config.API_BASE_URL}{config.TOKENS_PATH}"
+    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
+    _raise_for_status(resp, "create the service token")
+    return resp.json()
+
+
 def operation_stream_url(task_id: str) -> str:
     """URL for GET /api/v1/projects/operations/{task_id}/stream (SSE).
 

{mozbridge_cli-0.3.0 → mozbridge_cli-0.4.0}/src/mozbridge_cli/cmd_deploy.py

@@ -14,6 +14,33 @@ from .cmd_shared import require_link_and_session
 app = typer.Typer(add_completion=False)
 
 
+def _print_preflight_notice(preflight: dict) -> None:
+    """Print anything the platform's pre-deploy checks flagged, before the
+    confirm prompt. Silent when everything is clean — the happy path stays
+    exactly as quiet/fast as it was before this existed, no "10 lines of
+    ok" noise.
+
+    `preflight` is api.get_project_preflight's response
+    ({can_deploy, checks: [{key, level, title, detail, action}, ...], ...}
+    — see that function's docstring for the full shape). Only "warn"/"fail"
+    level checks are ever shown; "pass" checks are never printed.
+    """
+    checks = preflight.get("checks") or []
+    notable = [c for c in checks if c.get("level") in ("fail", "warn")]
+    if not notable:
+        return
+
+    typer.echo("The platform's pre-deploy checks found something to flag:")
+    for check in notable:
+        marker = "FAIL" if check.get("level") == "fail" else "WARN"
+        title = check.get("title") or check.get("key") or "(unnamed check)"
+        detail = check.get("detail") or ""
+        typer.echo(f"  [{marker}] {title}: {detail}")
+        if check.get("action"):
+            typer.echo(f"    action: {check['action']}")
+    typer.echo()
+
+
 @app.command("status")
 def status_cmd() -> None:
     """Show the linked project's status and its 5 most recent deployments."""
@@ -126,6 +153,24 @@ def deploy_cmd(
     Only the services you actually gave a tag for are deployed — `services`
     is built from --frontend/--backend, not left to the API's own default of
     both, unless you passed both.
+
+    Before the confirmation prompt, this also runs the platform's own
+    pre-deploy checks (GET .../preflight — the same 10 checks the backend
+    already runs reactively on every deploy attempt, covering placement,
+    host readiness, architecture, DNS, registry auth, disk, vault role,
+    site placement, secrets, and observability) and prints anything that
+    isn't clean, so a real, known-to-fail condition is visible before you
+    confirm rather than only after a rejected attempt. This is additive:
+    the existing reactive handling of a 409 preflight-blocked response
+    below is unchanged and still the actual enforcement point — this
+    earlier check is informational only and cannot itself refuse the
+    deploy. It does not check for a project's compose/template mismatch or
+    any other app-specific misconfiguration; that class of problem is
+    outside what these 10 checks cover. If the check itself cannot be run
+    (network error, backend error), this command notes that plainly and
+    still proceeds to the normal confirmation flow — matching the
+    backend's own fail-open design for this gate rather than being
+    stricter than the platform itself is.
     """
     if frontend is None and backend is None:
         typer.echo(
@@ -145,6 +190,17 @@ def deploy_cmd(
     with httpx.Client(timeout=30.0) as client:
         current_link, active_session = require_link_and_session(client, cwd)
 
+        try:
+            preflight = api.get_project_preflight(
+                client, active_session.access_token, current_link.org_id, current_link.project_id
+            )
+        except api.ApiError as exc:
+            typer.echo(f"Note: {exc} — proceeding without them.")
+        except Exception as exc:  # noqa: BLE001 - a preflight lookup failure must never block deploy
+            typer.echo(f"Note: could not run pre-deploy checks (error: {exc}) — proceeding without them.")
+        else:
+            _print_preflight_notice(preflight)
+
         project_desc = f"{current_link.org_slug}/{current_link.project_slug}"
         typer.echo(f"This will deploy {project_desc} ({environment}):")
         if frontend is not None: