stackport 0.4.7__tar.gz → 0.4.8__tar.gz

{stackport-0.4.7/stackport.egg-info → stackport-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackport
-Version: 0.4.7
+Version: 0.4.8
 Summary: Universal AWS resource browser for local emulators
 Author: Davi Reis Vieira
 License: MIT
@@ -314,7 +314,7 @@ stackport export lambda --format json
 stackport export ec2 --format csv
 ```
 
-`status`, `list`, `describe`, and `export` accept `--endpoint URL` and `--region REGION`. Without them they use `AWS_ENDPOINT_URL` and `AWS_REGION`, or the default endpoint saved in Settings.
+`status`, `list`, `describe`, and `export` accept `--endpoint` (a saved endpoint name or a URL) and `--region REGION`. Without `--endpoint` they use `AWS_ENDPOINT_URL` or the default endpoint saved in Settings. A saved endpoint brings its profile or keys, region and TLS settings (CA bundle, verification off) with it, and `--region` overrides its region. A URL passed directly uses no saved settings.
 
 ## Keyboard shortcuts
 
@@ -341,6 +341,7 @@ Press `?` anywhere to see all shortcuts.
 | `AWS_REGION` | `us-east-1` | AWS region |
 | `AWS_ACCESS_KEY_ID` | *(unset)* | AWS access key. Unset = use credential chain |
 | `AWS_SECRET_ACCESS_KEY` | *(unset)* | AWS secret key. Unset = use credential chain |
+| `AWS_SESSION_TOKEN` | *(unset)* | Session token for temporary credentials (SSO exports, assumed roles). Sent only with the two keys above. Read at start-up, so a new token needs a restart |
 | `AWS_PROFILE` | *(unset)* | AWS named profile from `~/.aws/config` |
 | `STACKPORT_PORT` | `8080` | StackPort server port |
 | `STACKPORT_HOST` | `127.0.0.1` | Interface StackPort listens on (`0.0.0.0` in the Docker image). StackPort has no login, so open it to the network only where that's fine |

{stackport-0.4.7 → stackport-0.4.8}/README.md

@@ -278,7 +278,7 @@ stackport export lambda --format json
 stackport export ec2 --format csv
 ```
 
-`status`, `list`, `describe`, and `export` accept `--endpoint URL` and `--region REGION`. Without them they use `AWS_ENDPOINT_URL` and `AWS_REGION`, or the default endpoint saved in Settings.
+`status`, `list`, `describe`, and `export` accept `--endpoint` (a saved endpoint name or a URL) and `--region REGION`. Without `--endpoint` they use `AWS_ENDPOINT_URL` or the default endpoint saved in Settings. A saved endpoint brings its profile or keys, region and TLS settings (CA bundle, verification off) with it, and `--region` overrides its region. A URL passed directly uses no saved settings.
 
 ## Keyboard shortcuts
 
@@ -305,6 +305,7 @@ Press `?` anywhere to see all shortcuts.
 | `AWS_REGION` | `us-east-1` | AWS region |
 | `AWS_ACCESS_KEY_ID` | *(unset)* | AWS access key. Unset = use credential chain |
 | `AWS_SECRET_ACCESS_KEY` | *(unset)* | AWS secret key. Unset = use credential chain |
+| `AWS_SESSION_TOKEN` | *(unset)* | Session token for temporary credentials (SSO exports, assumed roles). Sent only with the two keys above. Read at start-up, so a new token needs a restart |
 | `AWS_PROFILE` | *(unset)* | AWS named profile from `~/.aws/config` |
 | `STACKPORT_PORT` | `8080` | StackPort server port |
 | `STACKPORT_HOST` | `127.0.0.1` | Interface StackPort listens on (`0.0.0.0` in the Docker image). StackPort has no login, so open it to the network only where that's fine |

{stackport-0.4.7 → stackport-0.4.8}/backend/aws_client.py

@@ -47,6 +47,8 @@ def _build_client(service_name: str, plan: ConnectionPlan):
             session_kwargs["aws_access_key_id"] = plan.access_key_id
         if plan.secret_access_key is not None:
             session_kwargs["aws_secret_access_key"] = plan.secret_access_key
+        if plan.session_token is not None:
+            session_kwargs["aws_session_token"] = plan.session_token
         session = boto3.Session(**session_kwargs)
 
     client_kwargs: dict = {"service_name": service_name}

{stackport-0.4.7 → stackport-0.4.8}/backend/cli.py

@@ -12,13 +12,15 @@ import uvicorn
 from backend.aws_client import get_client
 from backend.config import (
     AWS_ENDPOINT_URL,
-    AWS_REGION,
+    ENDPOINTS,
     LOG_LEVEL,
     STACKPORT_HOST,
     STACKPORT_PORT,
     STACKPORT_SERVICES,
     endpoint_store,
 )
+from backend.connection import EndpointInfo, InvalidEndpointUrl
+from backend.routes.common import UnknownEndpoint, endpoint_info_for
 from backend.routes.resources import (
     DESCRIBE_REGISTRY,
     _PREFERRED_ID_FIELD,
@@ -30,16 +32,43 @@ from backend.routes.stats import SERVICE_REGISTRY, _METHOD_KWARGS, _count_items,
 logger = logging.getLogger(__name__)
 
 
+def _startup_endpoint_info() -> EndpointInfo:
+    """Connection info for AWS_ENDPOINT_URL, with the settings of the env endpoint it defines.
+
+    The store points that env endpoint (normally "default") at the environment's URL
+    for the run. If it was deleted, the URL is used on its own.
+    """
+    name = next((n for n, url in ENDPOINTS.items() if url == AWS_ENDPOINT_URL), None)
+    entry = endpoint_store.get(name) if name is not None else None
+    if entry is not None and entry["source"] == "env" and entry["url"] == AWS_ENDPOINT_URL:
+        return EndpointInfo.from_entry(entry)
+    return endpoint_info_for(AWS_ENDPOINT_URL)
+
+
 def _client_kwargs(endpoint: str | None, region: str | None) -> dict:
-    """Resolve where a CLI command talks to.
+    """Resolve where a CLI command talks to, the way the web app does.
 
-    An explicit --endpoint (or AWS_ENDPOINT_URL at startup) wins. Without one,
-    fall back to the saved default endpoint, the same one the web UI uses.
-    Passing the result to get_client explicitly is what makes the flag work
-    once ~/.stackport/endpoints.json exists.
+    ``endpoint`` is a saved endpoint's name or a URL. Without it, AWS_ENDPOINT_URL
+    at startup wins (with the settings of the env endpoint that defines it), then
+    the saved default endpoint. A saved endpoint brings its auth and TLS settings
+    along; an explicit ``region`` overrides its region. Passing the result to
+    get_client explicitly is what makes the flag work once
+    ~/.stackport/endpoints.json exists.
+
+    Raises:
+        click.BadParameter: the name matches no saved endpoint, or the URL is refused.
     """
-    url = endpoint if endpoint is not None else endpoint_store.get_default_url()
-    return {"endpoint_url": url, "region": region}
+    try:
+        if endpoint is None and AWS_ENDPOINT_URL is not None:
+            info = _startup_endpoint_info()
+        else:
+            info = endpoint_info_for(endpoint, strict=True)
+    except (InvalidEndpointUrl, UnknownEndpoint) as exc:
+        raise click.BadParameter(str(exc), param_hint="--endpoint") from exc
+    kwargs = info.client_kwargs()
+    if region is not None:
+        kwargs["region"] = region
+    return kwargs
 
 
 @click.group(invoke_without_command=True)
@@ -60,8 +89,8 @@ def serve(port, host):
 
 
 @cli.command()
-@click.option("--endpoint", default=AWS_ENDPOINT_URL, help="AWS endpoint URL", envvar="AWS_ENDPOINT_URL")
-@click.option("--region", default=AWS_REGION, help="AWS region", envvar="AWS_REGION")
+@click.option("--endpoint", default=None, help="Saved endpoint name or endpoint URL (default: AWS_ENDPOINT_URL if set, else the saved default endpoint)")
+@click.option("--region", default=None, help="AWS region (default: the endpoint's region, then AWS_REGION)")
 @click.option("--output", type=click.Choice(["json", "table"]), default="table", help="Output format")
 def status(endpoint, region, output):
     """Show all services with availability and resource counts."""
@@ -102,8 +131,8 @@ def status(endpoint, region, output):
 
 @cli.command()
 @click.argument("service")
-@click.option("--endpoint", default=AWS_ENDPOINT_URL, help="AWS endpoint URL", envvar="AWS_ENDPOINT_URL")
-@click.option("--region", default=AWS_REGION, help="AWS region", envvar="AWS_REGION")
+@click.option("--endpoint", default=None, help="Saved endpoint name or endpoint URL (default: AWS_ENDPOINT_URL if set, else the saved default endpoint)")
+@click.option("--region", default=None, help="AWS region (default: the endpoint's region, then AWS_REGION)")
 @click.option("--output", type=click.Choice(["json", "table", "csv"]), default="table", help="Output format")
 def list(service, endpoint, region, output):
     """List resources for a service."""
@@ -171,8 +200,8 @@ def list(service, endpoint, region, output):
 @click.argument("service")
 @click.argument("resource_type")
 @click.argument("resource_id")
-@click.option("--endpoint", default=AWS_ENDPOINT_URL, help="AWS endpoint URL", envvar="AWS_ENDPOINT_URL")
-@click.option("--region", default=AWS_REGION, help="AWS region", envvar="AWS_REGION")
+@click.option("--endpoint", default=None, help="Saved endpoint name or endpoint URL (default: AWS_ENDPOINT_URL if set, else the saved default endpoint)")
+@click.option("--region", default=None, help="AWS region (default: the endpoint's region, then AWS_REGION)")
 @click.option("--output", type=click.Choice(["json", "table"]), default="json", help="Output format")
 def describe(service, resource_type, resource_id, endpoint, region, output):
     """Describe a specific resource."""
@@ -253,8 +282,8 @@ def describe(service, resource_type, resource_id, endpoint, region, output):
 
 @cli.command()
 @click.argument("service")
-@click.option("--endpoint", default=AWS_ENDPOINT_URL, help="AWS endpoint URL", envvar="AWS_ENDPOINT_URL")
-@click.option("--region", default=AWS_REGION, help="AWS region", envvar="AWS_REGION")
+@click.option("--endpoint", default=None, help="Saved endpoint name or endpoint URL (default: AWS_ENDPOINT_URL if set, else the saved default endpoint)")
+@click.option("--region", default=None, help="AWS region (default: the endpoint's region, then AWS_REGION)")
 @click.option("--format", "format_", type=click.Choice(["json", "csv"]), default="json", help="Output format")
 @click.pass_context
 def export(ctx, service, endpoint, region, format_):

{stackport-0.4.7 → stackport-0.4.8}/backend/config.py

@@ -10,6 +10,11 @@ def _parse_aws_endpoint_url(environ: Mapping[str, str]) -> str | None:
     return environ.get("AWS_ENDPOINT_URL") or None
 
 
+def _parse_aws_credential(environ: Mapping[str, str], name: str) -> str | None:
+    """An access key, secret key or session token. Empty counts as unset (``AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}`` in Compose)."""
+    return environ.get(name, "").strip() or None
+
+
 AWS_ENDPOINT_URL: str | None = _parse_aws_endpoint_url(os.environ)
 
 # Remove AWS_ENDPOINT_URL from the process environment so boto3's internal
@@ -17,8 +22,10 @@ AWS_ENDPOINT_URL: str | None = _parse_aws_endpoint_url(os.environ)
 if "AWS_ENDPOINT_URL" in os.environ:
     del os.environ["AWS_ENDPOINT_URL"]
 AWS_REGION: str = os.environ.get("AWS_REGION", "us-east-1")
-AWS_ACCESS_KEY_ID: str | None = os.environ.get("AWS_ACCESS_KEY_ID")
-AWS_SECRET_ACCESS_KEY: str | None = os.environ.get("AWS_SECRET_ACCESS_KEY")
+AWS_ACCESS_KEY_ID: str | None = _parse_aws_credential(os.environ, "AWS_ACCESS_KEY_ID")
+AWS_SECRET_ACCESS_KEY: str | None = _parse_aws_credential(os.environ, "AWS_SECRET_ACCESS_KEY")
+# Belongs to the two keys above (SSO exports, assumed roles). Read once at start-up.
+AWS_SESSION_TOKEN: str | None = _parse_aws_credential(os.environ, "AWS_SESSION_TOKEN")
 STACKPORT_ALLOW_WRITES: bool = os.environ.get("STACKPORT_ALLOW_WRITES", "true").lower() in ("1", "true", "yes")
 STACKPORT_PORT: int = int(os.environ.get("STACKPORT_PORT", "8080"))
 # Interface the server listens on. Loopback by default: StackPort has no login

{stackport-0.4.7 → stackport-0.4.8}/backend/connection.py

@@ -8,7 +8,9 @@ Credentials, most specific first:
 
 1. the endpoint's own auth (a profile, or an access key pair);
 2. AWS Emulator's ``emulator_credentials`` for this endpoint, when present;
-3. ``AWS_ACCESS_KEY_ID`` / ``AWS_SECRET_ACCESS_KEY`` from StackPort's environment;
+3. ``AWS_ACCESS_KEY_ID`` / ``AWS_SECRET_ACCESS_KEY`` from StackPort's environment,
+   with ``AWS_SESSION_TOKEN`` when it is set (temporary credentials). The token
+   belongs to that pair only: no other source below or above ever gets it;
 4. placeholder keys when AWS Emulator's folder exists without keys (it runs
    with ``--auth off``, or it is stopped), so the default chain never sends the
    access key ID of a real account to it, and a stopped emulator shows up as
@@ -32,6 +34,7 @@ A plan is hashable and carries the emulator files' stat stamp, so
 
 from __future__ import annotations
 
+import hashlib
 import os
 import ssl
 from dataclasses import dataclass, field
@@ -43,7 +46,7 @@ from urllib3.exceptions import LocationParseError
 from urllib3.util import parse_url
 
 from backend import aws_emulator
-from backend.config import AWS_ACCESS_KEY_ID, AWS_REGION, AWS_SECRET_ACCESS_KEY, is_local_endpoint
+from backend.config import AWS_ACCESS_KEY_ID, AWS_REGION, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, is_local_endpoint
 
 CredentialSource = Literal[
     "endpoint-profile",
@@ -95,14 +98,21 @@ class EndpointInfo:
         """Prefix for cache keys holding this endpoint's results.
 
         Two saved endpoints can share a URL with different auth or TLS settings,
-        so all of them are in it (never the secret key). It starts with the URL,
-        so editing an endpoint, which drops ``"<url>:"`` keys, drops these too.
+        so all of them are in it. The secret key is there only as a short
+        digest, enough to tell two keys apart and useless for recovering one.
+        It starts with the URL, so editing an endpoint, which drops
+        ``"<url>:"`` keys, drops these too.
         """
+        secret_digest = (
+            hashlib.sha256(self.auth_secret_access_key.encode()).hexdigest()[:12]
+            if self.auth_secret_access_key
+            else None
+        )
         return ":".join(
             str(part)
             for part in (
                 self.url, self.region, self.auth_type, self.auth_profile,
-                self.auth_access_key_id, self.tls_verify, self.ca_bundle,
+                self.auth_access_key_id, secret_digest, self.tls_verify, self.ca_bundle,
             )
         )
 
@@ -131,6 +141,7 @@ class ConnectionPlan:
     profile: str | None = None
     access_key_id: str | None = field(default=None, repr=False)
     secret_access_key: str | None = field(default=None, repr=False)
+    session_token: str | None = field(default=None, repr=False)
     # None leaves verification to botocore (system trust, or AWS_CA_BUNDLE).
     verify: bool | str | None = None
     # A local emulator rather than AWS: see aws_client._build_client for what changes.
@@ -142,6 +153,15 @@ class InvalidEndpointUrl(ValueError):
     """An endpoint URL StackPort refuses to use."""
 
 
+def is_direct_endpoint_url(value: str | None) -> bool:
+    """True when an endpoint reference is a URL rather than a saved endpoint's name.
+
+    The scheme is case-insensitive (``HTTP://host`` is a URL); whether the URL
+    is acceptable is ``check_endpoint_url``'s call.
+    """
+    return value is not None and value.lower().startswith(("http://", "https://"))
+
+
 def check_endpoint_url(url: str) -> str:
     """Return ``url`` if it is a plain http(s) URL every parser reads the same way.
 
@@ -202,7 +222,7 @@ def plan_connection(ep: EndpointInfo) -> ConnectionPlan:
     files = aws_emulator.discover(ep.url) if ep.url and not (has_own_credentials and has_own_trust) else None
 
     # Credentials
-    profile = key = secret = None
+    profile = key = secret = token = None
     source: CredentialSource
     if ep.auth_type == "profile" and ep.auth_profile:
         source, profile = "endpoint-profile", ep.auth_profile
@@ -212,7 +232,7 @@ def plan_connection(ep: EndpointInfo) -> ConnectionPlan:
         key, secret = aws_emulator.read_credentials(files.credentials, files.stamp[1])
         source = "aws-emulator"
     elif AWS_ACCESS_KEY_ID is not None or AWS_SECRET_ACCESS_KEY is not None:
-        source, key, secret = "environment", AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
+        source, key, secret, token = "environment", AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
     elif files is not None:
         source, key, secret = "placeholder", PLACEHOLDER_ACCESS_KEY_ID, PLACEHOLDER_SECRET_ACCESS_KEY
     else:
@@ -240,6 +260,7 @@ def plan_connection(ep: EndpointInfo) -> ConnectionPlan:
         profile=profile,
         access_key_id=key,
         secret_access_key=secret,
+        session_token=token,
         verify=verify,
         local_endpoint=is_local_endpoint(ep.url),
         emulator_files=files,

stackport-0.4.8/backend/learn/cli_setup.py

@@ -0,0 +1,114 @@
+"""Extra shell setup the AWS CLI needs for the endpoint a learner is using.
+
+Lessons show commands like ``aws --endpoint-url={{endpointUrl}} s3 ls``. That
+is all MiniStack, Floci, LocalStack and Moto need. Some emulators also want
+environment variables, for example AWS Emulator, which serves HTTPS with a
+certificate and keys it creates at startup. The console steps work without
+any of that because StackPort reads the same files itself, so only the CLI
+path needs the learner to be told.
+
+``CLI_SETUP`` maps an emulator id (as reported by ``backend.emulators``) to a
+function returning the setup for it. An emulator that needs nothing has no
+entry, and the lesson shows nothing extra.
+"""
+
+from __future__ import annotations
+
+import shlex
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from backend import aws_emulator
+from backend.aws_emulator import AwsEmulatorFilesError
+from backend.connection import ConnectionPlan, plan_connection
+from backend.emulators import detect_emulator_quickly
+from backend.routes.common import EndpointInfo
+
+# Shell credentials outrank AWS_SHARED_CREDENTIALS_FILE, so leftovers would
+# sign requests with keys the emulator does not know.
+_CLEAR_CREDENTIALS = "unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE"
+
+
+@dataclass(frozen=True)
+class CliSetup:
+    """Shell lines to run once, and an optional sentence about where they come from."""
+
+    lines: list[str]
+    note: str | None = None
+
+
+def running_in_container() -> bool:
+    """True inside Docker or Podman, where StackPort's filesystem is not the learner's."""
+    return Path("/.dockerenv").exists() or Path("/run/.containerenv").exists()
+
+
+def _shell_path(path: Path) -> str:
+    """Render a path for pasting into a shell, keeping ``~`` for the home folder."""
+    shown = aws_emulator.display_path(path)
+    if not shown.startswith("~/"):
+        return shlex.quote(shown)
+    rest = shown[2:]
+    quoted = shlex.quote(rest)
+    return f"~/{rest}" if quoted == rest else f'"$HOME"/{quoted}'
+
+
+def _aws_emulator_setup(ep: EndpointInfo, plan: ConnectionPlan) -> CliSetup | None:
+    # Only when StackPort itself uses the emulator's files: an endpoint with its
+    # own keys or CA bundle is not one the CLI needs them for.
+    if "aws-emulator" not in (plan.credential_source, plan.trust_source):
+        return None
+    directory = aws_emulator.files_dir_for(ep.url)
+    if directory is None:
+        return None
+
+    note = None
+    if running_in_container():
+        # The folder StackPort sees is inside its container. AWS Emulator's own
+        # guide puts the files in the home folder of the machine running it.
+        port = directory.name
+        directory = Path.home() / ".aws" / "emulator" / port
+        note = (
+            "StackPort runs in a container, so these are the paths on your machine, where AWS Emulator "
+            "keeps its files when it runs there. With the Compose example the files live in the emulator's "
+            "volume: copy them out with `mkdir -p ~/.aws/emulator && docker compose -f "
+            f"docker-compose.aws-emulator.yml cp aws-emulator:/home/emulator/.aws/emulator/{port} "
+            "~/.aws/emulator/`, again after each restart."
+        )
+    return CliSetup(
+        lines=[
+            _CLEAR_CREDENTIALS,
+            f"export AWS_SHARED_CREDENTIALS_FILE={_shell_path(directory / aws_emulator.CREDENTIALS_FILE)}",
+            f"export AWS_CA_BUNDLE={_shell_path(directory / aws_emulator.CA_FILE)}",
+            # The emulator serves every service on one host, so the CLI must not
+            # prepend a service name to it (for example "s3-control.")
+            "export AWS_DISABLE_HOST_PREFIX_INJECTION=true",
+        ],
+        note=note,
+    )
+
+
+CLI_SETUP: dict[str, Callable[[EndpointInfo, ConnectionPlan], CliSetup | None]] = {
+    "aws-emulator": _aws_emulator_setup,
+}
+
+
+def cli_setup_for(ep: EndpointInfo) -> dict | None:
+    """The setup block for this endpoint, or None when the plain command works.
+
+    ``{"emulator": <display name>, "script": <shell lines>, "note": <sentence or None>}``.
+    Never probes an endpoint that is not saved, and waits only briefly for an
+    emulator that has not been identified yet, so the UI asks again later.
+    """
+    emulator = detect_emulator_quickly(ep)
+    builder = CLI_SETUP.get(emulator["id"]) if emulator else None
+    if builder is None:
+        return None
+    try:
+        plan = plan_connection(ep)
+    except AwsEmulatorFilesError:
+        return None
+    setup = builder(ep, plan)
+    if setup is None:
+        return None
+    return {"emulator": emulator["name"], "script": "\n".join(setup.lines), "note": setup.note}

{stackport-0.4.7 → stackport-0.4.8}/backend/routes/common.py

@@ -3,13 +3,19 @@
 from fastapi import HTTPException, Query
 
 from backend.config import endpoint_store
-from backend.connection import EndpointInfo, InvalidEndpointUrl, check_endpoint_url
+from backend.connection import EndpointInfo, InvalidEndpointUrl, check_endpoint_url, is_direct_endpoint_url
 
-__all__ = ["EndpointInfo", "endpoint_info_for", "endpoint_info_for_url", "get_endpoint_info", "get_endpoint_url"]
+__all__ = [
+    "EndpointInfo",
+    "UnknownEndpoint",
+    "endpoint_info_for",
+    "get_endpoint_info",
+    "get_endpoint_url",
+]
 
 
-def _is_direct_url(endpoint: str | None) -> bool:
-    return endpoint is not None and endpoint.startswith(("http://", "https://"))
+class UnknownEndpoint(LookupError):
+    """A name that matches no saved endpoint."""
 
 
 def get_endpoint_url(endpoint: str | None = Query(None, description="Endpoint name or URL")) -> str | None:
@@ -21,22 +27,29 @@ def get_endpoint_url(endpoint: str | None = Query(None, description="Endpoint na
     Returns:
         Endpoint URL to use for AWS API calls, or None for real AWS.
     """
-    if _is_direct_url(endpoint):
+    if is_direct_endpoint_url(endpoint):
         try:
-            check_endpoint_url(endpoint)
+            return check_endpoint_url(endpoint)
         except InvalidEndpointUrl as exc:
             raise HTTPException(status_code=422, detail=str(exc)) from exc
     return endpoint_store.resolve(endpoint)
 
 
-def endpoint_info_for(endpoint: str | None) -> EndpointInfo:
+def endpoint_info_for(endpoint: str | None, strict: bool = False) -> EndpointInfo:
     """Resolve an endpoint name, a direct URL, or None (the default) to connection info.
 
+    An unknown name falls back to the default endpoint, which suits HTTP routes;
+    ``strict`` raises instead, for callers where a typo shouldn't pick another endpoint.
+
     Raises:
         InvalidEndpointUrl: a direct URL StackPort refuses to use.
+        UnknownEndpoint: ``strict`` and the name matches no saved endpoint.
     """
-    if _is_direct_url(endpoint):
-        check_endpoint_url(endpoint)
+    if is_direct_endpoint_url(endpoint):
+        return EndpointInfo(url=check_endpoint_url(endpoint), region=None)
+    if strict and endpoint is not None and endpoint_store.get(endpoint) is None:
+        known = ", ".join(sorted(endpoint_store.list_all())) or "none"
+        raise UnknownEndpoint(f"'{endpoint}' is not a saved endpoint name or an http(s) URL. Saved endpoints: {known}.")
     entry = endpoint_store.resolve_full(endpoint)
     if entry:
         return EndpointInfo.from_entry(entry)
@@ -45,17 +58,6 @@ def endpoint_info_for(endpoint: str | None) -> EndpointInfo:
     return EndpointInfo(url=url, region=region)
 
 
-def endpoint_info_for_url(url: str | None) -> EndpointInfo:
-    """Connection info for a URL, using the first saved endpoint with that URL, if any.
-
-    For callers that only kept the URL, such as the WebSocket probe loop.
-    """
-    for entry in endpoint_store.list_all().values():
-        if entry["url"] == url:
-            return EndpointInfo.from_entry(entry)
-    return EndpointInfo(url=url, region=None)
-
-
 def get_endpoint_info(endpoint: str | None = Query(None, description="Endpoint name or URL")) -> EndpointInfo:
     """Resolve endpoint query param to URL, region, auth, and TLS config.
 

{stackport-0.4.7 → stackport-0.4.8}/backend/routes/endpoints.py

@@ -190,8 +190,9 @@ async def update_endpoint(name: str, body: UpdateEndpointBody):
         if old_url:
             cache.delete_by_prefix(f"{old_url}:")
 
-        # Broadcast change to connected clients
-        from backend.websocket import broadcast_endpoints_changed
+        # Broadcast change to connected clients; live stats kept under the old settings go too
+        from backend.websocket import broadcast_endpoints_changed, remove_endpoint_from_stats
+        remove_endpoint_from_stats(old_url)
         asyncio.create_task(broadcast_endpoints_changed())
 
         return {"name": name, **_public_entry(entry)}

{stackport-0.4.7 → stackport-0.4.8}/backend/routes/learn.py

@@ -19,6 +19,7 @@ from typing import Any
 from fastapi import APIRouter, Depends, HTTPException
 
 from backend.config import STACKPORT_DATA_DIR
+from backend.learn.cli_setup import cli_setup_for
 from backend.learn.verify import run_check
 from backend.learn_store import LearnProgressStore
 from backend.routes.common import EndpointInfo, get_endpoint_info
@@ -155,6 +156,17 @@ def get_trail(trail_id: str, ep: EndpointInfo = Depends(get_endpoint_info)) -> d
     }
 
 
+@router.get("/cli-setup")
+def get_cli_setup(ep: EndpointInfo = Depends(get_endpoint_info)) -> dict[str, Any]:
+    """What the CLI needs for this endpoint beyond ``--endpoint-url``, or null.
+
+    Separate from the trail because it can change without the trail changing:
+    an emulator is identified in the background, so the first answer may be
+    empty and the UI asks again.
+    """
+    return {"cliSetup": cli_setup_for(ep)}
+
+
 def _progress_payload(trail_id: str, progress: dict) -> dict[str, Any]:
     return {
         "completed": progress["completed"].get(trail_id, {}),