mozbridge-cli 0.1.0__py3-none-any.whl

mozbridge_cli/runtime_secrets.py

@@ -0,0 +1,140 @@
+"""Fetch + parse runtime build secrets for `mozbridge publish --local`.
+
+Talks to `GET /api/v1/projects/cicd/runtime-secrets`
+(backend/app/services/cicd_runtime_secrets.py, routed at
+backend/app/features/projects/router.py:get_cicd_runtime_secrets) — a
+completely DIFFERENT credential than the CLI's login session:
+
+    MOZBRIDGE_BUILD_TOKEN — a project-scoped ServiceToken with the 'build'
+    scope, authenticated by `_get_project_and_scopes_from_pipeline_token`.
+    A 'build' scope caller gets registry/build credentials and NEVER a
+    deploy host key (see that function's own docstring) — this is the
+    load-bearing security property that makes it safe to install this CLI
+    on a developer's laptop. Minting this token is a human action taken out
+    of band via the Mozbridge dashboard/API (existing create_service_token
+    mechanism) — this module only ever READS it from the environment.
+
+This module must never be handed the login session's access_token, and
+api.py's trigger_build/trigger_prebuilt_build (which DO use the login
+session) must never be handed MOZBRIDGE_BUILD_TOKEN. See main.py's
+`_publish_local` for how the two credentials are kept apart end to end.
+"""
+
+from __future__ import annotations
+
+import re
+
+import httpx
+
+from . import config
+
+BUILD_TOKEN_ENV_VAR = "MOZBRIDGE_BUILD_TOKEN"
+
+RUNTIME_SECRETS_PATH = f"{config.PROJECTS_PATH}/cicd/runtime-secrets"
+
+
+class RuntimeSecretsError(Exception):
+    """Raised when the runtime-secrets endpoint can't be reached or fails."""
+
+
+# One `export KEY=VALUE` (or bare `KEY=VALUE`) per line — exactly what
+# cicd_runtime_secrets.get_pipeline_secrets emits: `f"export {k}={_shell_quote(v)}"`
+# joined with newlines. The `export ` prefix is optional in this regex only
+# so the parser stays correct even if the backend response format loses it
+# some day; the real response always has it.
+_EXPORT_LINE_RE = re.compile(r"^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+
+
+def _unquote_shell_value(raw: str) -> str:
+    """Reverse cicd_runtime_secrets._shell_quote: `"'" + value.replace("'",
+    "'\\''") + "'"` — i.e. real POSIX-sh single-quoting, where an embedded
+    single quote becomes close-quote, escaped-literal-quote, reopen-quote
+    (`'\\''`). Walks the string rather than regexing it, since that
+    three-quote escape sequence is genuine (if unusual) shell syntax and
+    deserves a real parser instead of a pattern that happens to work on one
+    fixture.
+
+    Every value this backend ever emits is fully wrapped in single quotes
+    (see `_shell_quote` — there is no bare/unquoted-word case), so a `raw`
+    that doesn't start with `'` is returned unchanged rather than guessing
+    at a quoting style this backend doesn't use.
+    """
+    if not raw:
+        return ""
+    if raw[0] != "'":
+        return raw
+
+    parts: list[str] = []
+    i = 0
+    n = len(raw)
+    while i < n:
+        if raw[i] != "'":
+            # Anything between a closing quote and the next opening quote
+            # that ISN'T the `\'` escape (handled below) shouldn't occur in
+            # real output — skip defensively rather than raising on a
+            # response this CLI doesn't control.
+            i += 1
+            continue
+        i += 1  # step past the opening quote
+        end = raw.find("'", i)
+        if end == -1:
+            # Unterminated quote — best-effort: take the rest as literal.
+            parts.append(raw[i:])
+            break
+        parts.append(raw[i:end])
+        i = end + 1
+        if raw[i : i + 2] == "\\'":
+            parts.append("'")
+            i += 2
+    return "".join(parts)
+
+
+def parse_runtime_secrets(text: str) -> dict[str, str]:
+    """Parse the runtime-secrets endpoint's shell-sourceable response text
+    into a plain dict. Blank lines and comment lines (`#...`) are skipped;
+    any line that isn't `[export ]KEY=VALUE` is ignored rather than raising
+    — this is a real shell script, and being lenient about lines this
+    parser doesn't need is safer than a hard failure on a backend addition.
+    """
+    result: dict[str, str] = {}
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        match = _EXPORT_LINE_RE.match(stripped)
+        if not match:
+            continue
+        key, raw_value = match.group(1), match.group(2)
+        result[key] = _unquote_shell_value(raw_value)
+    return result
+
+
+def fetch_runtime_secrets(client: httpx.Client, build_token: str, *, env: str = "prod") -> dict[str, str]:
+    """GET /api/v1/projects/cicd/runtime-secrets?env=<env>, Bearer <build_token>.
+
+    No X-Organization-Id header is sent — unlike every human-session call
+    in api.py, `_get_project_and_scopes_from_pipeline_token` resolves both
+    the project and the caller's scopes from the token alone.
+    """
+    url = f"{config.API_BASE_URL}{RUNTIME_SECRETS_PATH}"
+    try:
+        resp = client.get(url, params={"env": env}, headers={"Authorization": f"Bearer {build_token}"})
+    except httpx.HTTPError as exc:
+        raise RuntimeSecretsError(f"Could not reach Mozbridge API for runtime secrets: {exc}") from exc
+
+    if resp.status_code == 401:
+        raise RuntimeSecretsError(
+            f"{BUILD_TOKEN_ENV_VAR} was rejected (401 Unauthorized). It must be an "
+            "active, project-scoped service token with the 'build' scope. Create one "
+            "via the Mozbridge dashboard/API (Project Settings -> Service Tokens), "
+            f"then `export {BUILD_TOKEN_ENV_VAR}=<token>` and try again."
+        )
+    if not (200 <= resp.status_code < 300):
+        try:
+            detail = resp.json().get("detail")
+        except ValueError:
+            detail = None
+        detail = detail or resp.text or f"HTTP {resp.status_code}"
+        raise RuntimeSecretsError(f"Could not fetch runtime secrets: {detail}")
+
+    return parse_runtime_secrets(resp.text)

mozbridge_cli/session.py

@@ -0,0 +1,156 @@
+"""Local session cache: read/write ~/.config/mozbridge/session.json.
+
+Security posture mirrors .llm/plans/_archived/ssh-broker.md's checklist for
+its analogous CLI ("stores user private keys with 0600 and in a directory
+with 0700") — applied here to session tokens instead of a private key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from . import config
+
+DIR_MODE = 0o700
+FILE_MODE = 0o600
+
+# Non-interactive/CI auth: a project-scoped ServiceToken (same primitive as
+# MOZBRIDGE_BUILD_TOKEN in runtime_secrets.py — created out of band via the
+# existing create_service_token mechanism, never minted by this CLI) used
+# directly as the bearer token for EVERY command instead of the on-disk
+# session file. This is a completely separate credential/purpose from
+# MOZBRIDGE_BUILD_TOKEN, which authenticates only `publish --local`'s
+# registry-secrets fetch — the two must never be read from, or written to,
+# the same place. See main.py's `_load_and_refresh_session` for the single
+# choke point where this takes precedence, and `login_cmd` for why
+# `mozbridge login` refuses outright when this is set (mutually exclusive
+# auth modes, same as gh CLI's GH_TOKEN precedence over a stored session).
+TOKEN_ENV_VAR = "MOZBRIDGE_TOKEN"
+
+
+@dataclass
+class Session:
+    access_token: str
+    refresh_token: str | None
+    id_token: str | None
+    expires_at: float  # unix timestamp, computed from expires_in at write time
+    scope: str | None = None
+    token_type: str = "Bearer"
+
+    def is_expired(self, *, leeway_seconds: int = 30) -> bool:
+        return time.time() >= (self.expires_at - leeway_seconds)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _ensure_config_dir() -> Path:
+    d = config.config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    os.chmod(d, DIR_MODE)
+    return d
+
+
+def save_session(session: Session) -> Path:
+    """Write the session file atomically with 0600 perms, dir with 0700."""
+    _ensure_config_dir()
+    path = config.session_path()
+    tmp_path = path.with_suffix(".tmp")
+
+    # Create with restrictive perms from the start (avoid a window where the
+    # file is briefly world/group readable), then atomically replace.
+    fd = os.open(tmp_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, FILE_MODE)
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(session.to_dict(), f, indent=2)
+            f.write("\n")
+    except BaseException:
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+
+    os.chmod(tmp_path, FILE_MODE)
+    os.replace(tmp_path, path)
+    os.chmod(path, FILE_MODE)
+    return path
+
+
+def load_session() -> Session | None:
+    """Return the cached session, or None if not logged in / file is unreadable."""
+    path = config.session_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    try:
+        return Session(
+            access_token=data["access_token"],
+            refresh_token=data.get("refresh_token"),
+            id_token=data.get("id_token"),
+            expires_at=float(data["expires_at"]),
+            scope=data.get("scope"),
+            token_type=data.get("token_type", "Bearer"),
+        )
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+def delete_session() -> bool:
+    """Remove the cached session file. Idempotent — returns whether a file was removed."""
+    path = config.session_path()
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def session_from_token_response(token_response: dict) -> Session:
+    """Build a Session from a Logto token-endpoint response, computing expires_at now."""
+    expires_in = float(token_response.get("expires_in", 3600))
+    return Session(
+        access_token=token_response["access_token"],
+        refresh_token=token_response.get("refresh_token"),
+        id_token=token_response.get("id_token"),
+        expires_at=time.time() + expires_in,
+        scope=token_response.get("scope"),
+        token_type=token_response.get("token_type", "Bearer"),
+    )
+
+
+def token_from_env() -> str | None:
+    """Return the CI bearer token from MOZBRIDGE_TOKEN, or None if unset/empty.
+
+    When this returns non-None, callers must use it directly as the bearer
+    token and skip load_session()/save_session()/refresh entirely — there is
+    no on-disk session file involved in this auth path at all, so the
+    0600/0700 permission checks (check_permissions_ok) never come into play
+    either.
+    """
+    value = os.environ.get(TOKEN_ENV_VAR)
+    return value if value else None
+
+
+def check_permissions_ok() -> bool:
+    """True if the config dir is 0700 and the session file (if present) is 0600."""
+    d = config.config_dir()
+    if not d.exists():
+        return True
+    dir_mode = stat.S_IMODE(d.stat().st_mode)
+    if dir_mode != DIR_MODE:
+        return False
+    path = config.session_path()
+    if path.exists():
+        file_mode = stat.S_IMODE(path.stat().st_mode)
+        if file_mode != FILE_MODE:
+            return False
+    return True

mozbridge_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,351 @@
+Metadata-Version: 2.5
+Name: mozbridge-cli
+Version: 0.1.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
+Project-URL: Repository, https://github.com/jessin01/mozbridge
+Author: Mozbridge
+License: Proprietary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mozbridge-cli
+
+A laptop CLI for the Mozbridge deployment platform. You sign in once via
+browser-based SSO (Logto's device-authorization flow — no password, no
+long-lived API key typed into a dotfile), link a local directory to a
+Mozbridge org + project, and push builds from there. It never holds a
+production credential of its own: every request it makes rides the same
+human Logto session `mozbridge login` cached, hitting the same REST API the
+Mozbridge web dashboard uses.
+
+macOS-only for v1 — there are no Windows code paths.
+
+## Install
+
+There is no published package yet (no PyPI entry, no `mozbridge-cli` on any
+index) — install from this checkout:
+
+```bash
+pip install -e cli/
+# or, for an isolated global install:
+pipx install ./cli
+```
+
+Either one registers a `mozbridge` console script (from
+`cli/pyproject.toml`'s `[project.scripts]`: `mozbridge =
+"mozbridge_cli.main:app_main"`). Confirm it's on your `PATH`:
+
+```bash
+mozbridge --help
+```
+
+Requires Python >= 3.10.
+
+## Quickstart
+
+```bash
+mozbridge login                                   # opens a browser to sign in
+cd ~/code/my-project
+mozbridge link --org acme --project web-app        # bind this directory
+mozbridge publish                                  # build + upload + trigger a build
+mozbridge status                                   # watch it land
+```
+
+Run `mozbridge link` with no flags to pick org/project from a numbered list
+interactively instead of naming slugs up front.
+
+## Commands
+
+```
+mozbridge login                                   # device-code SSO via Logto
+mozbridge whoami                                  # show the signed-in identity (refreshes the token if needed)
+mozbridge logout                                  # delete the cached local session
+mozbridge link [--org SLUG] [--project SLUG]      # link this directory to a Mozbridge org + project
+mozbridge build                                   # zip the current directory (does not upload)
+mozbridge publish                                 # build + upload + trigger a build on the linked project
+mozbridge diff                                    # preview what `publish` would do right now — makes no mutating call
+mozbridge status                                  # show the linked project + its 5 most recent deployments
+mozbridge rollback [--to ID] [--yes]              # roll back the linked project's deployment
+```
+
+Full flag-by-flag reference, example output, and every documented failure
+mode: **[docs/commands.md](docs/commands.md)**.
+
+## How project linking works
+
+`mozbridge link` writes `.mozbridge/link.json` in the **current directory**
+— not in the CLI's own `~/.config/mozbridge`. It records which org/project
+that specific repo checkout is bound to:
+
+```json
+{
+  "org_id": 1,
+  "org_slug": "acme",
+  "project_id": 10,
+  "project_slug": "web-app"
+}
+```
+
+This is per-repo working-tree state, not per-user CLI state — a fresh clone
+of the same repo on another machine has no link file until `mozbridge link`
+is run there too. **It is not committed.** `link` best-effort appends
+`.mozbridge/` to an existing `.gitignore` in the current directory (and
+tells you so); if there's no `.gitignore` there yet, it prints a note asking
+you to add the entry yourself rather than creating one. Either way: make
+sure `.mozbridge/` is actually gitignored in real repos, since the file
+contains real org/project identifiers.
+
+`build`, `publish`, `status`, and `rollback` all read this file and fail
+with a clear message if it's missing (see
+[docs/commands.md](docs/commands.md) for the exact text).
+
+## How multi-component publish works
+
+Most real Mozbridge tenants are multi-service (a backend + a frontend +
+workers), not a single whole-directory image. `mozbridge publish` detects
+this from a Compose file in the current directory and, when it finds one,
+publishes each buildable service as its own image — one
+`create_source_upload` → `PUT` → `trigger_build` cycle per component —
+instead of the single zip-the-whole-directory flow.
+
+**Discovery order** (Docker Compose's own file-discovery order, checked in
+this exact sequence, first match wins): `docker-compose.yml`,
+`compose.yaml`, `docker-compose.yaml`.
+
+**What counts as a "component"**: any top-level service in that file with a
+`build:` key — either the short form (`build: ./backend`) or the mapping
+form (`build: {context: ..., dockerfile: ...}`). A service with only an
+`image:` key (no `build:`) is not a component and is skipped — that's how a
+`redis:` or `postgres:` service in the same compose file is correctly
+ignored.
+
+**Shared-context de-duplication**: two components whose resolved build
+context is the same directory — even if spelled differently in YAML (`.`
+vs `./`) — are zipped and uploaded exactly once, then each triggers its own
+build reusing that one `upload_id`. This is genuinely a byte-savings and
+correctness behavior, not just a nicety: two services building from the
+same monorepo root would otherwise ship two identical uploads.
+
+**Per-component image naming**: each component's image name is computed
+client-side as
+`ghcr.io/{GHCR_ORG}/mozbridge-tenants/{org_slug}/{project_slug}-{service_name}`
+(the same base the backend computes by default for a single-component
+publish, with `-{service_name}` appended so N components never collide on
+one image).
+
+**Partial failure**: every component is attempted even if an earlier one
+fails — one broken service's build failing does not stop the others from
+being attempted. At the end, `publish` prints a summary line
+(`Publish summary: N succeeded, M failed (of TOTAL)`) followed by one `OK`
+or `FAIL` line per component, and exits non-zero if anything failed.
+
+**No compose file, or none of its services build**: `publish` falls back
+unchanged to the original single-component flow — zip the whole current
+directory, one upload, one `trigger_build` call, with no `image_name`,
+`context_path`, or `dockerfile_path` override sent, so the backend's own
+defaults apply exactly as they always have. This is the fallback path, not
+a separate mode you opt into — an ordinary non-Compose project (a single
+Dockerfile app, or no Dockerfile at all) publishes exactly as it did before
+multi-component support existed.
+
+## Security model
+
+- **Device-flow SSO, not a stored password or long-lived API key.**
+  `mozbridge login` runs Logto's OAuth 2.0 Device Authorization Grant (RFC
+  8628) against a real, provisioned Logto Native (public) client. You
+  approve the login in a browser; the CLI never sees or handles your
+  credentials directly.
+- **Session cache**: the resulting access/refresh/ID tokens are cached at
+  `~/.config/mozbridge/session.json`. The directory is created `0700` and
+  the file is written `0600` on every save (verified against real
+  filesystem state, not mocked — see `cli/tests/test_session_permissions.py`),
+  the same posture the project's SSH-broker design used for private key
+  material. An expired access token is refreshed transparently before any
+  command that needs one; if refresh itself fails (dead/revoked refresh
+  token, or none was ever cached) you're told to `mozbridge login` again
+  rather than being left in a half-authenticated state.
+- **What the CLI does NOT hold**: no service-token, no deploy credential, no
+  SSH key, no registry password. Every request uses the plain human Logto
+  bearer token `login` cached, sent exactly like a browser session would
+  send it.
+- **A real, documented platform gap — stated plainly, not alarmingly**:
+  today, request-level authorization for mutating project actions (publish,
+  rollback) beyond ordinary org/project membership is not yet enforced on
+  the backend for human-authenticated callers. Concretely:
+  `require_deploy_scope` (`backend/app/features/identity/token_scopes.py`)
+  is built on `require_token_scopes(...)`, whose check body returns
+  immediately — a complete no-op — for any caller that is not a
+  `mz_`-prefixed ServiceToken (`is_service_identity(user)` is `False` for a
+  plain human Logto token). The real gate a human session hits is ordinary
+  org/project membership (`get_current_org` + `get_valid_project`), not a
+  deploy-scope check. The `rollback/{deployment_id}` route has no scope
+  dependency on it at all. This is a **backend finding**, not something
+  introduced by or specific to this CLI — it applies equally to the web
+  dashboard's own session tokens, and it was surfaced (independently,
+  twice) while building this CLI's `publish` and `rollback` commands. It's
+  tracked as a known platform gap in `.llm/plans/gap-register.md` and in
+  the session notes at the end of `.llm/plans/mozbridge-agent.md` — not
+  something this doc oversells or that the CLI works around.
+
+## What's NOT built yet
+
+- **`mozbridge deploy`** — the platform-orchestrated deploy path
+  (`/cicd/deploy`). `publish` uses a different, already-working mechanism
+  (`create_source_upload` + `trigger_build` with `source_type="upload"`)
+  that builds fresh source into a new image — it does not go through
+  `/cicd/deploy` today.
+- Build-time secrets for multi-component publish.
+- Windows support.
+
+`mozbridge diff` (preview what `publish` would do, no mutating calls) is
+now built — see [docs/commands.md](docs/commands.md#mozbridge-diff). It
+compares local components against the most recent deployment *record*
+only, not the actually-deployed compose content — the platform doesn't
+expose that anywhere yet, so a full semantic compose diff is still not
+built.
+
+See `.llm/plans/mozbridge-agent.md` (the "Session progress and
+reconciliation" section at the end) for the full roadmap and how the CLI's
+scope compares to that plan's original acceptance criteria — not
+duplicated here.
+
+## CI / headless use
+
+Every command above assumes an interactive human at a terminal —
+`mozbridge login` opens a browser. A CI pipeline has neither, so instead of
+that stored session, set `MOZBRIDGE_TOKEN` in the pipeline environment:
+
+```bash
+export MOZBRIDGE_TOKEN=<service-token>
+mozbridge link --org acme --project web-app
+mozbridge publish
+```
+
+When `MOZBRIDGE_TOKEN` is set, it is used **directly as the bearer token for
+every command** — `whoami`, `link`, `status`, `rollback`, `diff`, and both
+`publish` and `publish --local`'s upload/registration calls — instead of the
+on-disk session `mozbridge login` produces. It's checked before anything
+session-file-related, so nothing under `~/.config/mozbridge/` is read,
+written, or permission-checked in this path at all. Because of that,
+`mozbridge login` itself refuses cleanly when `MOZBRIDGE_TOKEN` is set
+(these are mutually exclusive auth modes — a CI token in the environment
+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.
+
+**`MOZBRIDGE_TOKEN` vs `MOZBRIDGE_BUILD_TOKEN` — do not confuse these**:
+
+| | `MOZBRIDGE_TOKEN` | `MOZBRIDGE_BUILD_TOKEN` |
+|---|---|---|
+| Authenticates | **every** command, as a project-scoped identity | only `publish --local`'s one `GET /cicd/runtime-secrets` call |
+| Replaces | the entire `mozbridge login` session | nothing — it's used alongside your regular session, which still does the actual build registration |
+| Scope needed | whatever the platform grants a CI/service identity for the commands you run (link/publish/status/rollback) | the `build` scope specifically (registry/build credentials only, never a deploy host key) |
+
+They are two separate credentials for two separate purposes and are never
+read from, or substituted for, one another anywhere in this CLI — see
+`session.py` and `runtime_secrets.py`'s module docstrings.
+
+**A realistic Woodpecker pipeline step**:
+```yaml
+steps:
+  publish:
+    image: python:3.12-slim
+    environment:
+      MOZBRIDGE_TOKEN:
+        from_secret: mozbridge_token
+    commands:
+      - pip install --quiet mozbridge-cli   # or: pip install -e ./cli, per your setup
+      - mozbridge link --org acme --project web-app
+      - mozbridge publish
+```
+
+A GitHub Actions step looks the same, just spelled with `env:` and
+`${{ secrets.MOZBRIDGE_TOKEN }}`:
+```yaml
+      - name: Publish to Mozbridge
+        env:
+          MOZBRIDGE_TOKEN: ${{ secrets.MOZBRIDGE_TOKEN }}
+        run: |
+          mozbridge link --org acme --project web-app
+          mozbridge publish
+```
+
+`mozbridge link` still needs to run once per checkout (it writes
+`.mozbridge/link.json` into the working directory, which a fresh CI checkout
+never has) — there is no way to skip it by pre-seeding the link file today,
+so it belongs in the same pipeline step, before `publish`.
+
+## Configuration (advanced / override)
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `MOZBRIDGE_LOGTO_ENDPOINT` | `https://auth.mozbridge.com` | Logto tenant endpoint |
+| `MOZBRIDGE_LOGTO_CLIENT_ID` | `swdtsuiz6dgzack1g75x3` | Logto Native app client id (public client) |
+| `MOZBRIDGE_PUBLIC_API_URL` (falls back to `PUBLIC_API_URL`) | `https://api.mozbridge.com` | Mozbridge API base |
+| `MOZBRIDGE_GHCR_ORG` | `jessin01` | GHCR org used to compute default image names for multi-component publish |
+| `MOZBRIDGE_CONFIG_DIR` | `~/.config/mozbridge` | Where the session file lives (mainly for tests) |
+| `MOZBRIDGE_TOKEN` | unset | CI/headless auth — see [CI / headless use](#ci--headless-use) above |
+
+All of these have real, working defaults — the CLI works out of the box
+against production Mozbridge. The env vars exist for pointing at a
+non-production instance (and for test isolation).
+
+## Troubleshooting
+
+**"Not logged in. Run `mozbridge login` first."** — no session file
+exists yet at `~/.config/mozbridge/session.json` (or `whoami`/`link`/etc.
+was run before ever logging in). Run `mozbridge login`.
+
+**"Session expired and cannot be refreshed. Run `mozbridge login` again."**
+— your cached session has no refresh token. Re-run `mozbridge login`.
+
+**"Session refresh failed: ... — run `mozbridge login` again."** — the
+access token was expired and the cached refresh token was rejected by
+Logto (revoked, or itself expired). Re-run `mozbridge login`.
+
+**"Session is no longer valid. Run `mozbridge login` again."** (from
+`whoami` specifically) — the API returned 401 even with a token that looked
+valid client-side (e.g. revoked server-side). Re-run `mozbridge login`.
+
+**"This directory is not linked to a Mozbridge project. Run `mozbridge
+link` first."** — `build`/`publish`/`status`/`rollback` all require a
+`.mozbridge/link.json` in the current directory. Run `mozbridge link`
+(from the same directory you'll run these commands in).
+
+**A failed `publish`** — each step (`create_source_upload`, the `PUT`
+upload, `trigger_build`) surfaces the backend's own error `detail` text
+verbatim, prefixed with what it was trying to do, e.g.:
+
+```
+Could not upload the build source: Zip too large
+Could not create a source upload session: Not a member of this organization
+Could not trigger the build: <backend detail text>
+```
+
+For a multi-component publish, a failure on one component does not stop
+the others — you get a per-component `OK`/`FAIL` summary at the end (see
+[docs/commands.md](docs/commands.md#publish) for the exact shape) and the
+process exits non-zero if anything failed.

mozbridge_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+mozbridge_cli/__init__.py,sha256=g2NRvPMhAVHryZBlc7aqhnjsFYQUO6ttcZqOQUscOS4,108
+mozbridge_cli/__main__.py,sha256=x_rJ4JJtmcsX3-bdJcHN8TanBF7RNPtolGfIZjW3Zbo,70
+mozbridge_cli/api.py,sha256=bdKWjhjD-MvuRcu3NNGQ0yonSC44cEP3yjRdzijTun8,11139
+mozbridge_cli/auth.py,sha256=U4ffalUjmDxEivOtn4c3rvpiIs-YDAlJcCVpCTB11sA,5715
+mozbridge_cli/build.py,sha256=E9p9hLSqPG2kOOoAkkfIywIMePU_3QiUMW4PpbQm80E,3336
+mozbridge_cli/compose.py,sha256=n8i7d2BiNRwYtZ84sDNno5dDbeMihp9YIDjihYOaCgA,7212
+mozbridge_cli/config.py,sha256=DzVBM5sB-3lbB6OozePnJBsbG2U_CGreY95SK8sqUAc,3365
+mozbridge_cli/link.py,sha256=JbqYMOPprVeaS58kEjHgR7do2GooqQQEUwqb1oIpOLg,2824
+mozbridge_cli/local_build.py,sha256=3QNTOb6NMZaR5M5Zdg_V4aqt9o6Fpax97CBTcq_lo9Q,5555
+mozbridge_cli/main.py,sha256=FCQLmnPiqSRpLKxEtFZ_XA1VHPAykk7srHPFDVMgQq8,33277
+mozbridge_cli/runtime_secrets.py,sha256=q-8_Xf3NTI7S7qxD-LQ9p1s6pazn3XK2DwYzEly0wCo,5921
+mozbridge_cli/session.py,sha256=Fu7IAt-aOm7w78dTHSlmE9zJf3yhc28-dX-VxpocRbY,5275
+mozbridge_cli-0.1.0.dist-info/METADATA,sha256=Ua5Ars3fISrOlY4pfcWkONm4j7lP20c2Q4PEosIYeoA,16733
+mozbridge_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mozbridge_cli-0.1.0.dist-info/entry_points.txt,sha256=HWKL7SM6k13b49p6l8y7iTee0FaSSaugyQ52wgw9BiY,58
+mozbridge_cli-0.1.0.dist-info/RECORD,,

mozbridge_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mozbridge_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mozbridge = mozbridge_cli.main:app_main