delos-cli 0.1.0__py3-none-any.whl

delos_cli/auth/mfa.py

@@ -0,0 +1,120 @@
+"""Supabase MFA challenge for the CLI login flow.
+
+Compagnon's equivalent lives at ``apps/compagnon/src/hooks/use-auth.tsx`` — it
+calls ``supabase.auth.mfa.getAuthenticatorAssuranceLevel()`` then
+``mfa.challengeAndVerify({factorId, code})`` to upgrade an ``aal1`` session
+(freshly minted by ``/api/oauth/token``'s ``getSessionTokens`` magic-link path)
+to ``aal2``. We replicate that directly against the Supabase auth REST API so
+we don't pull in ``supabase-py`` just for these three calls.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+HTTP_ERROR_THRESHOLD = 400
+
+
+class MfaError(RuntimeError):
+    """Raised when the MFA upgrade fails (list, challenge, or verify)."""
+
+
+@dataclass
+class MfaFactor:
+    """A verified TOTP factor the user can challenge against."""
+
+    id: str
+    friendly_name: str
+
+
+@dataclass
+class UpgradedSession:
+    """The aal2 session Supabase returns after a successful verify."""
+
+    access_token: str
+    refresh_token: str
+    expires_in: int
+
+
+def decode_aal(access_token: str) -> str:
+    """Extract the ``aal`` claim from a Supabase JWT. Defaults to ``aal1``."""
+    parts = access_token.split(".")
+    if len(parts) < 2:  # noqa: PLR2004 — JWT shape is fixed
+        return "aal1"
+    payload_b64 = parts[1]
+    padding = (-len(payload_b64)) % 4
+    payload_b64 += "=" * padding
+    try:
+        payload = json.loads(base64.urlsafe_b64decode(payload_b64))
+    except (ValueError, json.JSONDecodeError):
+        return "aal1"
+    return str(payload.get("aal", "aal1"))
+
+
+async def list_verified_factors(
+    supabase_url: str, anon_key: str, access_token: str,
+) -> list[MfaFactor]:
+    """Return verified TOTP factors for the current user.
+
+    Supabase's JS ``mfa.listFactors()`` reads from ``GET /auth/v1/user`` and
+    extracts the ``factors`` array — there's no dedicated list endpoint for
+    regular users (``GET /auth/v1/factors`` is 405; it's POST-only for enroll).
+    """
+    headers = {"apikey": anon_key, "Authorization": f"Bearer {access_token}"}
+    async with httpx.AsyncClient(timeout=30.0) as http:
+        resp = await http.get(f"{supabase_url}/auth/v1/user", headers=headers)
+    if resp.status_code >= HTTP_ERROR_THRESHOLD:
+        msg = f"fetch user failed: HTTP {resp.status_code}: {resp.text[:200]}"
+        raise MfaError(msg)
+    user = resp.json()
+    factors_raw: list[dict[str, Any]] = user.get("factors") or []
+    return [
+        MfaFactor(id=str(f["id"]), friendly_name=str(f.get("friendly_name") or "TOTP"))
+        for f in factors_raw
+        if f.get("status") == "verified" and f.get("factor_type") == "totp"
+    ]
+
+
+async def challenge_and_verify(
+    supabase_url: str,
+    anon_key: str,
+    access_token: str,
+    factor_id: str,
+    code: str,
+) -> UpgradedSession:
+    """Run Supabase's challenge + verify flow, returning fresh aal2 tokens."""
+    headers = {
+        "apikey": anon_key,
+        "Authorization": f"Bearer {access_token}",
+        "Content-Type": "application/json",
+    }
+    base = f"{supabase_url}/auth/v1/factors/{factor_id}"
+    async with httpx.AsyncClient(timeout=30.0) as http:
+        chal = await http.post(f"{base}/challenge", headers=headers)
+        if chal.status_code >= HTTP_ERROR_THRESHOLD:
+            msg = f"challenge failed: HTTP {chal.status_code}: {chal.text[:200]}"
+            raise MfaError(msg)
+        challenge_id = chal.json().get("id")
+        if not challenge_id:
+            msg = f"challenge response missing id: {chal.text[:200]}"
+            raise MfaError(msg)
+
+        verify = await http.post(
+            f"{base}/verify",
+            headers=headers,
+            json={"challenge_id": challenge_id, "code": code},
+        )
+    if verify.status_code >= HTTP_ERROR_THRESHOLD:
+        msg = f"verify failed: HTTP {verify.status_code}: {verify.text[:200]}"
+        raise MfaError(msg)
+    data = verify.json()
+    return UpgradedSession(
+        access_token=str(data["access_token"]),
+        refresh_token=str(data["refresh_token"]),
+        expires_in=int(data.get("expires_in", 3600)),
+    )

delos_cli/auth/oauth.py

@@ -0,0 +1,336 @@
+"""OAuth PKCE loopback flow for `delos login`.
+
+Reuses the same `/authorize` + `/api/oauth/token` endpoints that the compagnon
+browser extension uses. Steps:
+
+1. Register a `Delos CLI` OAuth client via RFC 7591 dynamic registration
+   (cached per-config so subsequent logins skip this step).
+2. Generate a PKCE S256 verifier/challenge pair.
+3. Spin up a one-shot HTTP server on 127.0.0.1:<free_port>/callback.
+4. Open the browser to {web}/authorize with offline_access scope.
+5. Catch the redirect, exchange the code at /api/oauth/token, persist tokens.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import contextlib
+import hashlib
+import http.server
+import json
+import secrets
+import socket
+import threading
+import time
+import webbrowser
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+
+from .config import Config, Tokens
+from .mfa import (
+    MfaError,
+    challenge_and_verify,
+    decode_aal,
+    list_verified_factors,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from .mfa import MfaFactor
+
+REDIRECT_PATH = "/callback"
+CALLBACK_TIMEOUT_SECONDS = 600
+DEFAULT_EXPIRES_IN = 3600
+HTTP_ERROR_THRESHOLD = 400
+
+# Canonical CLI client, pre-registered in oauth_clients.
+# Must match the row inserted by the infra SQL migration.
+CLIENT_ID = "delos-cli"
+LOOPBACK_PORT = 52700
+
+_SUCCESS_HTML = (
+    b"<!doctype html><html><head><meta charset='utf-8'>"
+    b"<title>Delos CLI</title></head><body style='font-family:sans-serif;padding:3rem'>"
+    b"<h1>Signed in.</h1><p>You can close this tab.</p></body></html>"
+)
+_ERROR_HTML = (
+    b"<!doctype html><html><head><meta charset='utf-8'>"
+    b"<title>Delos CLI</title></head><body style='font-family:sans-serif;padding:3rem'>"
+    b"<h1>Sign-in failed.</h1><p>Check the terminal for details.</p></body></html>"
+)
+
+
+class OAuthError(RuntimeError):
+    """Raised when the OAuth flow fails at any step."""
+
+
+class RefreshTokenInvalidError(OAuthError):
+    """The refresh token itself is invalid/revoked — the user must re-login.
+
+    Distinguished from transient refresh failures (network, 5xx) so that
+    callers can surface a "run ``delos login``" message instead of a retry.
+    """
+
+
+@dataclass
+class LoginResult:
+    """Outcome of a successful OAuth handshake."""
+
+    tokens: Tokens
+    user_id: str
+    org_uuid: str
+    client_id: str
+
+
+def _pkce_pair() -> tuple[str, str]:
+    """Generate an RFC 7636 S256 verifier/challenge pair."""
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
+    digest = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+def _check_port_free(port: int) -> None:
+    """Confirm the loopback port is bindable, with a clear error if not."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("127.0.0.1", port))
+    except OSError as e:
+        msg = (
+            f"loopback port {port} is in use — close whatever is holding it "
+            f"(try `lsof -iTCP:{port}`) and re-run `delos login`"
+        )
+        raise OAuthError(msg) from e
+
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    """One-shot request handler: captures `code`/`state` and signals the main thread."""
+
+    result: ClassVar[dict[str, str]] = {}
+    event: ClassVar[threading.Event] = threading.Event()
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path != REDIRECT_PATH:
+            self.send_response(404)
+            self.end_headers()
+            return
+        params = parse_qs(parsed.query)
+        code = params.get("code", [""])[0]
+        state = params.get("state", [""])[0]
+        error = params.get("error", [""])[0]
+        if error or not code:
+            self._send_html(400, _ERROR_HTML)
+            type(self).result = {"error": error or "missing code"}
+        else:
+            self._send_html(200, _SUCCESS_HTML)
+            type(self).result = {"code": code, "state": state}
+        type(self).event.set()
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002 — stdlib signature
+        """Silence the default stderr access log."""
+
+    def _send_html(self, status: int, body: bytes) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+async def _exchange_code(
+    web_url: str,
+    client_id: str,
+    redirect_uri: str,
+    code: str,
+    verifier: str,
+) -> dict[str, Any]:
+    """Swap the authorization code for Supabase tokens at /api/oauth/token."""
+    async with httpx.AsyncClient(timeout=30.0) as http:
+        resp = await http.post(
+            f"{web_url}/api/oauth/token",
+            json={
+                "grant_type": "authorization_code",
+                "code": code,
+                "code_verifier": verifier,
+                "client_id": client_id,
+                "redirect_uri": redirect_uri,
+                "scope": "offline_access",
+            },
+        )
+    if resp.status_code >= HTTP_ERROR_THRESHOLD:
+        msg = f"token exchange failed: HTTP {resp.status_code}: {resp.text[:300]}"
+        raise OAuthError(msg)
+    return resp.json()
+
+
+async def run_login_flow(
+    cfg: Config,
+    on_message: Callable[[str], None],
+    prompt_code: Callable[[str], Awaitable[str]],
+) -> LoginResult:
+    """Drive the full PKCE loopback flow — returns tokens on success, raises on failure.
+
+    If the user has a verified TOTP MFA factor, runs Supabase's challenge+verify
+    flow client-side (same trick compagnon uses) to upgrade the fresh ``aal1``
+    session to ``aal2`` so RLS ``mfa_enforcement`` policies don't block writes.
+    ``prompt_code`` is awaited to get the 6-digit code from the user.
+    """
+    _check_port_free(LOOPBACK_PORT)
+    redirect_uri = f"http://127.0.0.1:{LOOPBACK_PORT}{REDIRECT_PATH}"
+    verifier, challenge = _pkce_pair()
+    state = secrets.token_urlsafe(16)
+    client_id = CLIENT_ID
+
+    params = {
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "response_type": "code",
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "state": state,
+        "scope": "offline_access",
+    }
+    authorize_url = f"{cfg.web_url}/authorize?{urlencode(params)}"
+
+    _CallbackHandler.result = {}
+    _CallbackHandler.event = threading.Event()
+    server = http.server.HTTPServer(("127.0.0.1", LOOPBACK_PORT), _CallbackHandler)
+    thread = threading.Thread(target=server.handle_request, daemon=True)
+    thread.start()
+
+    on_message(f"Open this URL to sign in:\n  {authorize_url}")
+    with contextlib.suppress(webbrowser.Error):
+        webbrowser.open(authorize_url)
+
+    loop = asyncio.get_running_loop()
+    got_callback = await loop.run_in_executor(
+        None, _CallbackHandler.event.wait, CALLBACK_TIMEOUT_SECONDS,
+    )
+    server.server_close()
+
+    if not got_callback:
+        msg = f"no OAuth callback within {CALLBACK_TIMEOUT_SECONDS}s"
+        raise OAuthError(msg)
+    result = _CallbackHandler.result
+    if "error" in result:
+        msg = f"OAuth error: {result['error']}"
+        raise OAuthError(msg)
+    if result.get("state") != state:
+        msg = "OAuth state mismatch (possible CSRF)"
+        raise OAuthError(msg)
+
+    on_message("Exchanging authorization code…")
+    token_data = await _exchange_code(
+        cfg.web_url, client_id, redirect_uri, result["code"], verifier,
+    )
+
+    access = str(token_data.get("supabase_access_token") or token_data.get("access_token", ""))
+    refresh = str(token_data.get("supabase_refresh_token") or token_data.get("refresh_token", ""))
+    expires_in = int(token_data.get("expires_in", DEFAULT_EXPIRES_IN))
+
+    access, refresh, expires_in = await _maybe_upgrade_to_aal2(
+        cfg, access, refresh, expires_in, on_message, prompt_code,
+    )
+
+    return LoginResult(
+        tokens=Tokens(
+            access_token=access,
+            refresh_token=refresh,
+            expires_at=int(time.time()) + expires_in,
+        ),
+        user_id=str(token_data.get("user_id", "")),
+        org_uuid=str(token_data.get("org_uuid", "")),
+        client_id=client_id,
+    )
+
+
+async def _maybe_upgrade_to_aal2(
+    cfg: Config,
+    access: str,
+    refresh: str,
+    expires_in: int,
+    on_message: Callable[[str], None],
+    prompt_code: Callable[[str], Awaitable[str]],
+) -> tuple[str, str, int]:
+    """If the session is aal1 and the user has a TOTP factor, run the challenge flow."""
+    if decode_aal(access) == "aal2":
+        return access, refresh, expires_in
+
+    try:
+        factors = await list_verified_factors(cfg.supabase_url, cfg.supabase_anon_key, access)
+    except MfaError as e:
+        on_message(f"warning: couldn't list MFA factors ({e}); continuing at aal1")
+        return access, refresh, expires_in
+
+    if not factors:
+        return access, refresh, expires_in
+
+    factor = _pick_factor(factors, on_message)
+    on_message(f"MFA required — challenging factor '{factor.friendly_name}'")
+    code = (await prompt_code(f"Enter 6-digit code for {factor.friendly_name}: ")).strip()
+    try:
+        upgraded = await challenge_and_verify(
+            cfg.supabase_url, cfg.supabase_anon_key, access, factor.id, code,
+        )
+    except MfaError as e:
+        msg = f"MFA verification failed: {e}"
+        raise OAuthError(msg) from e
+    on_message("MFA verified — session upgraded to aal2.")
+    return upgraded.access_token, upgraded.refresh_token, upgraded.expires_in
+
+
+def _pick_factor(factors: list[MfaFactor], on_message: Callable[[str], None]) -> MfaFactor:
+    """Pick a factor automatically when there's only one; otherwise print the list and use the first."""
+    if len(factors) == 1:
+        return factors[0]
+    on_message("Multiple TOTP factors found — using the first:")
+    for i, f in enumerate(factors):
+        on_message(f"  [{i}] {f.friendly_name}")
+    return factors[0]
+
+
+HTTP_BAD_REQUEST = 400
+
+
+async def refresh_tokens(cfg: Config) -> Tokens:
+    """Swap the refresh token for a fresh access token at /api/oauth/token.
+
+    Raises :class:`RefreshTokenInvalidError` when the server reports
+    ``invalid_grant`` (token revoked, expired, or already rotated by another
+    client) — the caller should prompt for re-login. Other failures raise
+    :class:`OAuthError` and are generally transient.
+    """
+    if not cfg.tokens.refresh_token:
+        msg = "no refresh_token stored — run `delos login` again"
+        raise RefreshTokenInvalidError(msg)
+    async with httpx.AsyncClient(timeout=30.0) as http:
+        resp = await http.post(
+            f"{cfg.web_url}/api/oauth/token",
+            json={
+                "grant_type": "refresh_token",
+                "refresh_token": cfg.tokens.refresh_token,
+                "client_id": CLIENT_ID,
+            },
+        )
+    if resp.status_code == HTTP_BAD_REQUEST:
+        with contextlib.suppress(json.JSONDecodeError, ValueError):
+            err = resp.json()
+            if isinstance(err, dict) and err.get("error") == "invalid_grant":
+                msg = str(err.get("error_description") or "refresh token is invalid or expired")
+                raise RefreshTokenInvalidError(msg)
+    if resp.status_code >= HTTP_ERROR_THRESHOLD:
+        msg = f"refresh failed: HTTP {resp.status_code}: {resp.text[:300]}"
+        raise OAuthError(msg)
+    data = resp.json()
+    expires_in = int(data.get("expires_in", DEFAULT_EXPIRES_IN))
+    return Tokens(
+        access_token=str(data["access_token"]),
+        refresh_token=str(data.get("refresh_token", cfg.tokens.refresh_token)),
+        expires_at=int(time.time()) + expires_in,
+    )

delos_cli/auth/token_manager.py

@@ -0,0 +1,136 @@
+"""Single source of truth for access/refresh tokens at runtime.
+
+Models the behavior of Supabase JS's ``autoRefreshToken: true`` — the one
+``apps/compagnon`` relies on to stay signed in "forever" without ever seeing
+401s from expired access tokens:
+
+* **Proactive refresh**: every time the CLI needs an access token, we check
+  the JWT's ``exp`` claim; if we're within ``LEEWAY_SECONDS`` of expiry we
+  refresh first and hand back the fresh one.
+* **Reactive refresh**: if the server rejects an otherwise-valid-looking
+  token (401/403 — could be an admin revocation or clock skew), callers hit
+  :meth:`force_refresh` which bypasses the expiry check.
+* **In-process safety**: an :class:`asyncio.Lock` serializes refreshes so a
+  burst of 20 concurrent requests with an expired token triggers exactly one
+  refresh, not twenty.
+* **Cross-process safety**: :func:`config_file_lock` + re-read from disk
+  inside the critical section means two ``delos`` terminals running at once
+  can't each burn the same refresh token against Supabase and lose.
+* **Atomic persistence**: writes go through :func:`save`, which does
+  tempfile + ``fsync`` + ``os.replace``.
+* **Typed failure modes**: :class:`RefreshTokenInvalidError` surfaces only
+  when the refresh token itself is dead (``invalid_grant``) — callers
+  translate that into "run ``delos login``"; anything else is transient.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import time
+from typing import TYPE_CHECKING
+
+from .config import Tokens, config_file_lock, load, save
+from .oauth import refresh_tokens
+
+if TYPE_CHECKING:
+    from .config import Config
+
+# Refresh this many seconds before the access token actually expires.
+# Picked to absorb network RTT and clock drift without being so eager we
+# churn refreshes for idle REPLs.
+LEEWAY_SECONDS = 60
+
+
+class TokenManager:
+    """Owns the live ``Config.tokens`` for a single CLI process.
+
+    One instance per ``AuthedClient``. Not thread-safe (asyncio-only); that's
+    fine — the CLI runs one event loop. Concurrency inside the loop and
+    across sibling processes is handled explicitly via the locks below.
+    """
+
+    def __init__(self, cfg: Config) -> None:
+        """Bind the manager to a ``Config``; mutations land in it in-place."""
+        self._cfg = cfg
+        self._lock = asyncio.Lock()
+
+    @property
+    def cfg(self) -> Config:
+        """The live ``Config`` — URL properties are read directly from it."""
+        return self._cfg
+
+    async def access_token(self) -> str:
+        """Return a non-near-expiry access token, refreshing first if needed."""
+        if self._near_expiry():
+            await self._refresh()
+        return self._cfg.tokens.access_token
+
+    async def force_refresh(self) -> None:
+        """Refresh unconditionally — call after the server returned 401/403.
+
+        Still honors the in-process + cross-process locks and the
+        disk-adoption shortcut, so a burst of 401s won't multiply refreshes.
+        """
+        await self._refresh(force=True)
+
+    def _near_expiry(self) -> bool:
+        """True when the access token's ``exp`` is within LEEWAY of now."""
+        exp = _jwt_exp(self._cfg.tokens.access_token) or self._cfg.tokens.expires_at
+        if not exp:
+            return True  # no token, or no exp claim — treat as expired
+        return exp - int(time.time()) < LEEWAY_SECONDS
+
+    async def _refresh(self, *, force: bool = False) -> None:
+        async with self._lock:
+            # Double-check under the in-process lock: another coroutine may
+            # have just refreshed while we awaited the lock.
+            if not force and not self._near_expiry():
+                return
+
+            # Cross-process lock. Re-read the file inside it — another CLI
+            # may have refreshed and written fresh tokens since we started.
+            with config_file_lock():
+                disk = load()
+                if not force and _is_fresher(disk.tokens, self._cfg.tokens):
+                    self._cfg.tokens = disk.tokens
+                    return
+
+                # We're the one doing the refresh. Use whichever refresh
+                # token is most recent (ours if unchanged, or the one from
+                # disk if another process wrote a newer pair we missed).
+                if _is_fresher(disk.tokens, self._cfg.tokens):
+                    self._cfg.tokens = disk.tokens
+
+                # On failure (RefreshTokenInvalidError / OAuthError) we
+                # let the exception propagate and intentionally do NOT
+                # wipe the on-disk tokens — a stale-in-memory vs.
+                # fresh-on-disk mismatch (or a transient backend error)
+                # shouldn't cost the user their session.  The caller
+                # surfaces "run delos login" and the user decides.
+                self._cfg.tokens = await refresh_tokens(self._cfg)
+                save(self._cfg)
+
+
+def _jwt_exp(access_token: str) -> int | None:
+    """Return the ``exp`` claim (seconds since epoch) from a JWT, or None."""
+    parts = access_token.split(".")
+    min_jwt_parts = 2
+    if len(parts) < min_jwt_parts:
+        return None
+    payload_b64 = parts[1]
+    payload_b64 += "=" * ((-len(payload_b64)) % 4)
+    try:
+        payload = json.loads(base64.urlsafe_b64decode(payload_b64))
+    except (ValueError, json.JSONDecodeError):
+        return None
+    exp = payload.get("exp")
+    if isinstance(exp, int):
+        return exp
+    return None
+
+
+def _is_fresher(a: Tokens, b: Tokens) -> bool:
+    """True when ``a`` represents a session that will live longer than ``b``."""
+    return bool(a.access_token) and a.expires_at > b.expires_at

delos_cli/commands/__init__.py

@@ -0,0 +1,10 @@
+"""Command primitives + the global command registry.
+
+App-specific commands live under ``apps/<name>/commands.py`` and are
+merged on top of ``GLOBAL_COMMANDS`` by the completer and the loop.
+"""
+
+from .base import CommandSpec, Quit, registry_from
+from .builtin import GLOBAL_COMMANDS
+
+__all__ = ["GLOBAL_COMMANDS", "CommandSpec", "Quit", "registry_from"]

delos_cli/commands/base.py

@@ -0,0 +1,54 @@
+"""Command primitives: the spec + the control-flow signal."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Iterable
+
+    from delos_cli.ctx import Ctx
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """One slash command.
+
+    ``handler`` may be sync or async. ``complete`` is optional and is called
+    by the completer to suggest argument values — it receives the raw string
+    that follows the command name (may be empty).
+    """
+
+    name: str
+    summary: str
+    handler: Callable[[Ctx, str], Awaitable[None] | None]
+    aliases: tuple[str, ...] = ()
+    complete: Callable[[Ctx, str], Iterable[str]] | None = None
+    args_hint: str = ""
+
+    @property
+    def display_name(self) -> str:
+        """Command name + optional arg hint for help / toolbar."""
+        return f"{self.name} {self.args_hint}".rstrip()
+
+
+class Quit(BaseException):
+    """Control-flow signal raised by ``/quit`` to unwind the REPL loop.
+
+    Subclasses ``BaseException`` on purpose: bare ``except Exception`` handlers
+    inside command/app code must not swallow it.
+    """
+
+
+def registry_from(specs: Iterable[CommandSpec]) -> dict[str, CommandSpec]:
+    """Build a name→spec dict that also covers every alias of every spec."""
+    out: dict[str, CommandSpec] = {}
+    for spec in specs:
+        out[spec.name] = spec
+        for alias in spec.aliases:
+            out[alias] = spec
+    return out
+
+
+__all__ = ["CommandSpec", "Quit", "registry_from"]