deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/config.py

@@ -0,0 +1,352 @@
+"""Configuration and credentials management.
+
+Stores config in ``~/.deepcell/config.json`` and credentials in
+``~/.deepcell/credentials.json`` (mode 0600).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+_DIR = Path.home() / ".deepcell"
+_CONFIG_FILE = _DIR / "config.json"
+_CREDS_FILE = _DIR / "credentials.json"
+
+# ── Defaults ────────────────────────────────────────────────
+
+DEFAULT_API_URL = "https://beta.deepcell.net/api/jingwei"
+DEFAULT_FORMAT = "plain"
+
+# ── Environment overrides ───────────────────────────────────
+
+ENV_API_URL = "DEEPCELL_API_URL"
+ENV_API_URL_FALLBACK = "JINGWEI_API_URL"
+ENV_ACCESS_TOKEN = "DEEPCELL_ACCESS_TOKEN"
+ENV_PROJECT = "DEEPCELL_PROJECT"
+#: The pre-rename spelling. Still honored — an exported variable lives in
+#: people's CI config and shell profiles, where a rename is a silent break.
+ENV_WORKSPACE = "DEEPCELL_WORKSPACE"
+ENV_CONFIG = "DEEPCELL_CONFIG"
+#: Which surface is calling. Unset means the CLI itself; the MCP server sets it
+#: to ``mcp`` because it runs commands through this same package in-process, so
+#: without it an agent's tool call is indistinguishable from a human at a
+#: terminal — two different products sharing one funnel.
+ENV_CLIENT = "DEEPCELL_CLIENT"
+
+# ── Caller identification ──────────────────────────────────
+
+#: Mirrors ``HEADER`` in ``backend/jingwei_api/analytics/client_surface.py``,
+#: which parses it and stamps it onto every audit row. The duplication is
+#: unavoidable (separate packages, no shared runtime) and the failure mode is
+#: silent — a rename on one side degrades every CLI row to NULL — so
+#: ``backend/jingwei_api/tests/test_client_surface_taxonomy.py`` diffs the two.
+CLIENT_HEADER = "X-DeepCell-Client"
+
+#: The surfaces this package may legitimately claim to be. `browser` is
+#: deliberately absent: the server would accept it, and a CLI that could
+#: announce itself as a browser would quietly corrupt the one number this
+#: header exists to produce.
+CLIENT_SURFACES = ("cli", "mcp")
+
+DEFAULT_CLIENT_SURFACE = "cli"
+
+# ── TLS warning tracking ───────────────────────────────────
+
+#: API URLs already warned about in this process. The MCP server runs many
+#: commands in one process, so this is what keeps it to one warning there.
+_insecure_warned: set[str] = set()
+
+#: API URLs already warned about from this config, across processes. A shell
+#: agent runs one process per command, so "once per process" was every
+#: command — 55+ copies of the same line per task, each one prefixed to the
+#: output the agent was actually reading. The marker lives beside the config
+#: (see :func:`state_file`), so a session-scoped ``DEEPCELL_CONFIG`` warns
+#: once per session and a changed ``api_url`` warns again.
+INSECURE_WARNED_FILE = "insecure-http-warned.json"
+
+
+def _ensure_dir() -> None:
+    _DIR.mkdir(parents=True, exist_ok=True, mode=0o700)
+    # Fix permissions if directory was created by older code
+    try:
+        _DIR.chmod(0o700)
+    except OSError:
+        pass
+
+
+def _write_private_file(path: Path, content: str) -> None:
+    """Write *content* to *path* with mode 0600.
+
+    The **permissions** are atomic, which is the property that matters for a
+    file holding a token: ``os.open`` with ``O_CREAT | O_WRONLY | O_TRUNC``
+    creates it 0600, so it never exists world-readable, not even briefly.
+
+    The **content** is not. ``O_TRUNC`` empties the file before the write, so
+    a crash mid-write leaves it truncated and the caller re-authenticates.
+    That is the accepted trade: a temp-file-and-rename would survive the crash
+    but writes through a symlink differently and changes the inode every save,
+    and nothing here is worth that. Do not describe this function as an atomic
+    write.
+    """
+    fd = os.open(
+        str(path),
+        os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+        0o600,
+    )
+    # Only this narrow window owns the raw fd. Once `fdopen` takes it, the
+    # file object owns it and closing it here too would be a double close —
+    # on a recycled fd number that is somebody else's file.
+    try:
+        handle = os.fdopen(fd, "w")
+    except BaseException:
+        os.close(fd)
+        raise
+    with handle as f:
+        f.write(content)
+
+
+def warn_if_insecure(api_url: str) -> None:
+    """Warn on stderr, once per API URL per config, when *api_url* uses
+    plain HTTP against a non-localhost host.
+
+    Loud the first time: the whole warning plus where the acknowledgement
+    is recorded. Silent after that — the marker file beside the config
+    remembers the URL, so the warning is not repeated on every command a
+    shell agent runs. If the marker cannot be written the warning stays
+    per-process, which is the old behaviour and still correct.
+    """
+    parsed = urlparse(api_url)
+    if parsed.scheme != "http":
+        return
+    host = parsed.hostname or ""
+    if host in ("localhost", "127.0.0.1", "::1"):
+        return
+    if api_url in _insecure_warned:
+        return
+    _insecure_warned.add(api_url)
+    if api_url in _load_insecure_warned():
+        return
+    marker = state_file(INSECURE_WARNED_FILE)
+    try:
+        _record_insecure_warned(api_url)
+        where = f"Shown once per API URL; recorded in {marker}."
+    except OSError:
+        where = f"Could not record this in {marker}, so it will repeat."
+    print(
+        f"WARNING: sending credentials over plain HTTP to {host}. "
+        "Use HTTPS for non-localhost servers.\n"
+        f"         {where}",
+        file=sys.stderr,
+    )
+
+
+def _load_insecure_warned() -> list[str]:
+    """API URLs the marker file says were already warned about."""
+    path = state_file(INSECURE_WARNED_FILE)
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return []
+    urls = data.get("api_urls") if isinstance(data, dict) else None
+    return [u for u in urls if isinstance(u, str)] if isinstance(urls, list) else []
+
+
+def _record_insecure_warned(api_url: str) -> None:
+    urls = _load_insecure_warned()
+    if api_url not in urls:
+        urls.append(api_url)
+    save_state_file(INSECURE_WARNED_FILE, {"api_urls": urls})
+
+
+# ── Config (api_url, active_workspace, default_format) ──────
+
+
+def _config_file() -> Path:
+    """Resolve the config path: DEEPCELL_CONFIG env > ~/.deepcell/config.json.
+
+    DEEPCELL_CONFIG gives each job a session-scoped config so parallel
+    processes never race on the shared file (issue #1017). Credentials are
+    deliberately NOT redirected — login state stays shared.
+    """
+    env = os.environ.get(ENV_CONFIG)
+    if env:
+        return Path(env).expanduser()
+    return _CONFIG_FILE
+
+
+def load_config() -> dict[str, Any]:
+    """Load the config file, returning defaults if missing."""
+    path = _config_file()
+    if path.exists():
+        return json.loads(path.read_text())
+    return {}
+
+
+def save_config(data: dict[str, Any]) -> None:
+    """Write config to disk (mode 0600)."""
+    path = _config_file()
+    if path is _CONFIG_FILE:
+        _ensure_dir()
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    _write_private_file(path, json.dumps(data, indent=2) + "\n")
+
+
+def state_file(name: str) -> Path:
+    """Path to a small state file living beside the resolved config file.
+
+    Deliberately *beside the config*, not always in ``~/.deepcell``: a job
+    given a session-scoped ``DEEPCELL_CONFIG`` gets session-scoped state too,
+    so parallel processes never race on a shared cache and a test that
+    redirects the config redirects the cache with it.
+    """
+    return _config_file().parent / name
+
+
+def save_state_file(name: str, data: dict[str, Any]) -> None:
+    """Write *data* as JSON to :func:`state_file` (mode 0600)."""
+    path = state_file(name)
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    _write_private_file(path, json.dumps(data, indent=2) + "\n")
+
+
+def get_api_url() -> str:
+    """Resolve API URL: DEEPCELL_API_URL > JINGWEI_API_URL > config > default."""
+    env = os.environ.get(ENV_API_URL)
+    if env:
+        return env.rstrip("/")
+    env_fallback = os.environ.get(ENV_API_URL_FALLBACK)
+    if env_fallback:
+        return env_fallback.rstrip("/")
+    cfg = load_config()
+    return cfg.get("api_url", DEFAULT_API_URL).rstrip("/")
+
+
+def get_client_surface() -> str:
+    """Which surface is calling: ``cli`` (default) or ``mcp``.
+
+    Read from the environment on every call rather than cached at import: the
+    MCP server invokes this package in-process through ``CliRunner``, setting
+    the variable per invocation, so a value captured at import time would be
+    whatever the first caller happened to be.
+
+    An unrecognised value falls back to ``cli`` rather than being forwarded.
+    This header is a self-declaration, so the server validates it anyway; the
+    point of validating here too is that a typo in someone's shell profile
+    should degrade to "a CLI called us" — which is true — instead of dropping
+    the surface entirely.
+    """
+    raw = (os.environ.get(ENV_CLIENT) or "").strip().lower()
+    return raw if raw in CLIENT_SURFACES else DEFAULT_CLIENT_SURFACE
+
+
+def client_headers(surface: str | None = None) -> dict[str, str]:
+    """The ``X-DeepCell-Client`` header every request to the API carries.
+
+    Sent on every call, authenticated or not. The surface used to be visible
+    only on the anonymous-mint body, so a signed-in CLI session was entirely
+    unattributed — which is most of the sessions worth counting.
+
+    ``surface`` overrides the environment lookup, for callers that know what
+    they are without being told: the MCP server's own OAuth machinery runs in
+    the server process, not inside a ``CliRunner`` invocation, so
+    ``DEEPCELL_CLIENT`` is not set there and it would otherwise report ``cli``.
+    """
+    from . import __version__
+
+    resolved = surface if surface in CLIENT_SURFACES else get_client_surface()
+    return {CLIENT_HEADER: f"{resolved}/{__version__}"}
+
+
+def get_active_workspace() -> str | None:
+    """Resolve the active project: env var > config file."""
+    env = os.environ.get(ENV_PROJECT) or os.environ.get(ENV_WORKSPACE)
+    if env:
+        return env
+    return load_config().get("active_workspace")
+
+
+def set_active_workspace(slug: str) -> None:
+    """Persist active workspace in config."""
+    cfg = load_config()
+    cfg["active_workspace"] = slug
+    save_config(cfg)
+
+
+def get_default_format() -> str:
+    return load_config().get("default_format", DEFAULT_FORMAT)
+
+
+# ── Credentials (access_token, refresh_token, …) ───────────
+
+
+def load_credentials() -> dict[str, Any]:
+    """Load ``~/.deepcell/credentials.json``."""
+    if _CREDS_FILE.exists():
+        return json.loads(_CREDS_FILE.read_text())
+    return {}
+
+
+def save_credentials(data: dict[str, Any]) -> None:
+    """Write credentials to disk (mode 0600, atomic permissions)."""
+    _ensure_dir()
+    _write_private_file(_CREDS_FILE, json.dumps(data, indent=2) + "\n")
+
+
+def clear_credentials() -> None:
+    """Remove credentials file."""
+    if _CREDS_FILE.exists():
+        _CREDS_FILE.unlink()
+
+
+def get_access_token() -> str | None:
+    """Resolve access token: env var > credentials file."""
+    env = os.environ.get(ENV_ACCESS_TOKEN)
+    if env:
+        return env
+    return load_credentials().get("access_token")
+
+
+def get_refresh_token() -> str | None:
+    return load_credentials().get("refresh_token")
+
+
+def frontend_base_url() -> str:
+    """Web-app base URL for links the CLI prints (share/viewer URLs).
+
+    ``FRONTEND_URL`` / ``DEEPCELL_FRONTEND_URL`` env vars win; otherwise the
+    URL is derived from the API URL (scheme + host — deployments serve the
+    frontend at ``/`` and the API under ``/api/jingwei`` on the same host).
+    Local dev stacks run the frontend on its own port, so export
+    ``FRONTEND_URL=http://localhost:3000`` there.
+    """
+    from urllib.parse import urlparse
+
+    env = os.environ.get("FRONTEND_URL") or os.environ.get("DEEPCELL_FRONTEND_URL")
+    if env:
+        return env.rstrip("/")
+    api_url = get_api_url()
+    parsed = urlparse(api_url)
+    if not parsed.scheme or not parsed.hostname:
+        return api_url  # malformed API URL — pass it through rather than guess
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def is_anonymous_session() -> bool:
+    """True when the stored credentials are an anonymous demo session.
+
+    Anonymous sessions are minted by the client from ``POST /demo/session``
+    (see ``DeepCellClient``); they carry ``anonymous: true`` plus the
+    server-issued ``device_id`` identity secret instead of a refresh token.
+    """
+    return bool(load_credentials().get("anonymous"))
+
+
+def get_anon_device_id() -> str | None:
+    """The server-issued anonymous identity secret, if any."""
+    return load_credentials().get("device_id")

deepcell_cli/context.py

@@ -0,0 +1,187 @@
+"""Shared Click context (``Ctx`` + ``pass_ctx``) for the ``deepcell`` CLI.
+
+Lives in its own module so command sub-modules can import it without pulling
+in ``deepcell_cli.main``, which transitively re-imports every command module
+to register them on the root group. Importing a command module directly (e.g.
+from a parity test) used to trip a circular import via ``main``.
+"""
+
+from __future__ import annotations
+
+import os
+
+import click
+
+from deepcell_cli.client import DeepCellClient
+
+
+class Ctx:
+    """Object carried through Click context for shared state."""
+
+    def __init__(
+        self, *, verbose: bool = False, fmt: str = "plain", workspace: str | None = None
+    ) -> None:
+        self.verbose = verbose
+        self.fmt = fmt
+        self.workspace = workspace
+        self._client: DeepCellClient | None = None
+
+    @property
+    def client(self) -> DeepCellClient:
+        if self._client is None:
+            # Resolved here, not stored at the root callback: there it is only
+            # the group name. No `self.command or …` override — a settable
+            # field would let a caller reintroduce exactly that.
+            self._client = DeepCellClient(
+                verbose=self.verbose, command=self._command_path()
+            )
+        return self._client
+
+    @staticmethod
+    def _command_path() -> str | None:
+        """Full invoked command, e.g. ``defs add-item`` — not just the group.
+
+        The root group only knows ``invoked_subcommand`` (``defs``), which is
+        the least useful half of the answer when this lands in a commit trailer
+        and, from there, in the Changes feed. The client is built lazily inside
+        the leaf command, so by now Click's context stack knows the whole path.
+
+        Built by walking the context chain rather than splitting
+        ``command_path``: the program name is not always one token. Under
+        ``python -m deepcell_cli`` Click reports it as ``python -m
+        deepcell_cli``, so dropping a single token left ``-m deepcell_cli defs
+        add-item`` — which the server's header validator rejects outright for
+        its leading dash, silently losing the trailer that this exists to send.
+        """
+        try:
+            ctx = click.get_current_context(silent=True)
+            if ctx is None:
+                return None
+            names: list[str] = []
+            # The root context's `info_name` IS the program name; everything
+            # below it is a real command token.
+            while ctx.parent is not None:
+                if ctx.info_name:
+                    names.append(ctx.info_name)
+                ctx = ctx.parent
+            return " ".join(reversed(names)) or None
+        except Exception:
+            return None
+
+    def require_workspace(self) -> str:
+        """Return the active workspace slug, auto-selecting if possible."""
+        from deepcell_cli.config import get_active_workspace, set_active_workspace
+        from deepcell_cli.errors import ConfigError
+
+        if self.workspace:
+            return self.workspace
+
+        from deepcell_cli.config import ENV_WORKSPACE
+
+        env_ws = os.environ.get(ENV_WORKSPACE)
+        if env_ws:
+            return env_ws
+
+        # Inside a cloned workspace folder, that clone wins over the global
+        # config. `clone` never sets the active workspace, so commands that
+        # resolve through here (log / diff / restore / variant …) used to
+        # target whatever slug happened to be active — `deepcell restore` in
+        # ws-a/ rolled back a *different* workspace and reported success.
+        sync_slug = self._sync_root_workspace()
+        if sync_slug:
+            return sync_slug
+
+        ws = get_active_workspace()
+        if ws:
+            return ws
+
+        try:
+            workspaces = self.client.get("/workspaces")
+        except click.ClickException:
+            # Auth / connection / API errors carry the actionable message
+            # (e.g. "Not authenticated. Run `deepcell login` first.") — never
+            # mask them behind a workspace-selection hint.
+            raise
+        except Exception:
+            raise ConfigError("No active project. Run `deepcell project use <slug>` first.")
+
+        if not workspaces or not isinstance(workspaces, list) or len(workspaces) == 0:
+            from deepcell_cli.config import is_anonymous_session
+
+            if is_anonymous_session():
+                return self._create_scratch_workspace()
+            raise ConfigError("No projects found. Create one with `deepcell project create <name>`.")
+
+        if len(workspaces) == 1:
+            slug = workspaces[0].get("slug", "")
+            set_active_workspace(slug)
+            click.echo(f"Using project '{slug}' (only project available)", err=True)
+            return slug
+
+        from deepcell_cli.config import is_anonymous_session
+
+        if is_anonymous_session():
+            # An anonymous session is ONE identity with no account behind it,
+            # so "which of your workspaces did you mean?" has no answer the
+            # caller could give — and the caller is usually an agent, for whom
+            # a selection prompt is a dead end mid-task. Pick, and say which.
+            #
+            # Prefer the demo-kind one, because that is what every anonymous
+            # surface on the server already resolves: the find-or-create in
+            # `ensure_workspace_for_anonymous` and the `prefer_demo` thread
+            # binding both filter `kind = 'demo'`, and the DB allows only one
+            # live per creator (`ux_one_live_demo_workspace_per_user`). Picking
+            # anything else here would put the CLI and the browser on different
+            # workspaces for the same identity.
+            chosen = next(
+                (w for w in workspaces if w.get("kind") == "demo"), workspaces[0]
+            )
+            slug = chosen.get("slug", "")
+            if slug:
+                set_active_workspace(slug)
+                click.echo(f"Using project '{slug}'", err=True)
+                return slug
+
+        slugs = [w.get("slug", "?") for w in workspaces]
+        listing = "\n".join(f"  - {s}" for s in slugs)
+        raise ConfigError(
+            f"Multiple projects available:\n{listing}\n\nSelect one with `deepcell project use <slug>`."
+        )
+
+    @staticmethod
+    def _sync_root_workspace() -> str | None:
+        """Workspace slug recorded in an enclosing clone's ``.deepcell/sync.json``."""
+        try:
+            from deepcell_cli.sync_state import find_sync_root, load_sync_state
+
+            root = find_sync_root()
+            if root is None:
+                return None
+            state = load_sync_state(root)
+            return getattr(state, "workspace_slug", None) or None
+        except Exception:
+            # A malformed/unreadable sync file must not break commands that
+            # would otherwise resolve the workspace from config.
+            return None
+
+    def _create_scratch_workspace(self) -> str:
+        """Create and activate a scratch workspace for an anonymous session.
+
+        Anonymous users start with no workspace at all; instead of telling
+        them to run `deepcell project create` we provision one so the first
+        `write`/`query` just works. The server treats it like any other
+        workspace owned by the anon user, so a later `deepcell login` carries
+        it into the real account.
+        """
+        import secrets
+
+        from deepcell_cli.config import set_active_workspace
+
+        slug = f"scratch-{secrets.token_hex(4)}"
+        self.client.post("/workspaces", json={"name": "Scratch workspace", "slug": slug})
+        set_active_workspace(slug)
+        click.echo(f"Created workspace '{slug}'", err=True)
+        return slug
+
+
+pass_ctx = click.make_pass_decorator(Ctx, ensure=True)

deepcell_cli/errors.py

@@ -0,0 +1,141 @@
+"""Error types for the DeepCell CLI."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+import httpx
+
+
+class APIError(click.ClickException):
+    """Raised when the API returns a non-2xx response.
+
+    ``payload`` carries the parsed JSON ``detail`` when it was structured
+    (dict/list) so commands can render rich errors (e.g. replace conflicts);
+    ``detail`` is always the flattened string form.
+
+    ``headers`` carries the response headers, because some of what a caller
+    needs to *act* on an error is only there and never in the body: the write
+    surfaces answer a 409 with ``X-Conflict-Reason`` and ``X-Current-Revision``
+    (see ``jingwei_api/conflict.py``), and /batch-edit + /apply-defs-ops send
+    the reason in the header alone. Without this the CLI could only tell those
+    conflicts apart by matching on the English of ``detail``, which stops
+    working the first time someone rewords the message.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: str,
+        payload: object | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        self.payload = payload
+        self.headers = headers or {}
+        super().__init__(f"[{status_code}] {detail}")
+
+    def format_message(self) -> str:  # noqa: D102
+        # For user-facing errors (4xx), show the detail directly without "API error" wrapper
+        if 400 <= self.status_code < 500:
+            return self.detail
+        return f"API error ({self.status_code}): {self.detail}"
+
+
+class EmailVerificationRequired(APIError):
+    """Raised when the API rejects a request because email is not verified."""
+
+    def __init__(self, detail: str = "Email verification required") -> None:
+        super().__init__(403, detail)
+
+    def format_message(self) -> str:  # noqa: D102
+        return (
+            "Email verification required. "
+            "Run `deepcell verify-email` to verify your email address."
+        )
+
+
+class AccountRequiredError(APIError):
+    """A 401/403 hit while running in an anonymous demo session.
+
+    The server-side detail is kept (it says *what* was denied); the appended
+    hint turns the dead end into the way forward — signing in.
+    """
+
+    def format_message(self) -> str:  # noqa: D102
+        return (
+            f"{self.detail}\n"
+            "This needs an account. Run `deepcell login` to sign in."
+        )
+
+
+class SessionExpiredError(APIError):
+    """A 401 that survived a refresh attempt on a signed-in session.
+
+    The credentials no longer work: the refresh token was missing, rejected, or
+    revoked. Without this, the bare 401 detail from the server reached the user
+    unexplained — the one failure in the CLI that looked like a permissions
+    problem and was really "sign in again". An agent reading that has no reason
+    to stop retrying, which is the worst response to it.
+
+    ``from_env`` picks the fix that actually works. When the token came from
+    ``DEEPCELL_ACCESS_TOKEN`` the environment wins over the credentials file
+    (see ``config.get_access_token``), so telling that caller to sign in would
+    send it in a circle: `deepcell login` writes a file the env var then
+    overrides, and the next command fails identically.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: str,
+        payload: object | None = None,
+        *,
+        from_env: bool = False,
+    ) -> None:
+        super().__init__(status_code, detail, payload=payload)
+        self.from_env = from_env
+
+    def format_message(self) -> str:  # noqa: D102
+        fix = (
+            "The token in DEEPCELL_ACCESS_TOKEN is no longer valid. Replace it, "
+            "or unset it to use the credentials from `deepcell login`."
+            if self.from_env
+            else "Your session has expired. Run `deepcell login` to sign in again."
+        )
+        return f"{fix}\n(the server said: {self.detail})"
+
+
+class AuthError(click.ClickException):
+    """Raised when authentication fails or is missing."""
+
+    def __init__(self, message: str = "Not authenticated. Run `deepcell login` first.") -> None:
+        super().__init__(message)
+
+
+class ConnectionError(click.ClickException):
+    """Raised when the CLI cannot connect to the API server."""
+
+    def __init__(self, url: str, cause: Exception) -> None:
+        self.url = url
+        if "Connection refused" in str(cause):
+            hint = "Is the API server running?"
+        elif isinstance(cause, httpx.TimeoutException):
+            hint = "The request timed out."
+        else:
+            hint = str(cause)
+        super().__init__(f"Could not connect to {url} — {hint}")
+
+
+class ConfigError(click.ClickException):
+    """Raised for configuration problems (missing workspace, etc.)."""
+
+    pass
+
+
+def die(message: str, code: int = 1) -> None:
+    """Print an error to stderr and exit."""
+    click.echo(f"Error: {message}", err=True)
+    sys.exit(code)