urun-cli 0.5.2__tar.gz → 0.5.3__tar.gz

{urun_cli-0.5.2 → urun_cli-0.5.3}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.3
+
+- Publish the previously-unreleased `urun app purge` and `urun build purge`
+  subcommands. Both landed on `main` after the `v0.5.2` tag was cut, and the
+  release workflow skips re-publishing when the `pyproject` version is unchanged,
+  so they were never available on PyPI. This is a version-bump-only release that
+  carries the existing, already-tested commands to PyPI so CI/operators can run
+  `uvx --from urun-cli==0.5.3 urun app purge <slug>` (hard-delete orphaned app
+  metadata after `urun app delete`) without a private git install. No CLI
+  behavior changes beyond making these commands installable.
+
 ## Unreleased
 
 - Make `urun deploy` resilient to transient network blips. The manifest/blob

{urun_cli-0.5.2 → urun_cli-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urun-cli
-Version: 0.5.2
+Version: 0.5.3
 Summary: End-user CLI for deploying apps to urun
 Project-URL: Homepage, https://urun.sh
 Project-URL: Repository, https://github.com/urun-sh/urun-cli
@@ -51,21 +51,26 @@ uvx urun-cli --version
 
 ## Quick start
 
-Today, an operator manually vends an org-scoped deploy API key. Save it locally
-with `urun login`:
+Save an org-scoped deploy API key locally with `urun login`:
 
 ```bash
-urun login --api-key urun_<32hex>
+urun login
 ```
 
-`urun login` verifies the key with the urun API and stores credentials for later
-commands. The future browser-based login flow is not available in this CLI
-release.
+If `URUN_API_KEY` is not already set, `urun login` opens the urun console API
+keys page, prompts you to paste the generated `urun_sk_...` key, verifies it
+with the urun API, and stores credentials for later commands.
+
+If you already have a key, you can pass it directly:
+
+```bash
+urun login --api-key urun_sk_<secret>
+```
 
 For CI or one-off commands, you can still use the environment variable:
 
 ```bash
-export URUN_API_KEY=urun_<32hex>
+export URUN_API_KEY=urun_sk_<secret>
 ```
 
 Create `app.py`:

{urun_cli-0.5.2 → urun_cli-0.5.3}/README.md

@@ -29,21 +29,26 @@ uvx urun-cli --version
 
 ## Quick start
 
-Today, an operator manually vends an org-scoped deploy API key. Save it locally
-with `urun login`:
+Save an org-scoped deploy API key locally with `urun login`:
 
 ```bash
-urun login --api-key urun_<32hex>
+urun login
 ```
 
-`urun login` verifies the key with the urun API and stores credentials for later
-commands. The future browser-based login flow is not available in this CLI
-release.
+If `URUN_API_KEY` is not already set, `urun login` opens the urun console API
+keys page, prompts you to paste the generated `urun_sk_...` key, verifies it
+with the urun API, and stores credentials for later commands.
+
+If you already have a key, you can pass it directly:
+
+```bash
+urun login --api-key urun_sk_<secret>
+```
 
 For CI or one-off commands, you can still use the environment variable:
 
 ```bash
-export URUN_API_KEY=urun_<32hex>
+export URUN_API_KEY=urun_sk_<secret>
 ```
 
 Create `app.py`:

{urun_cli-0.5.2 → urun_cli-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "urun-cli"
-version = "0.5.2"
+version = "0.5.3"
 description = "End-user CLI for deploying apps to urun"
 readme = "README.md"
 requires-python = ">=3.11"

{urun_cli-0.5.2 → urun_cli-0.5.3}/src/urun/api.py

@@ -180,6 +180,11 @@ class ApiClient:
             f"/cli/builds/{urllib.parse.quote(build_id, safe='')}/logs", {"tail": tail}
         )
 
+    def purge_build(self, manifest_hash_or_prefix: str) -> dict[str, Any]:
+        return self._delete(
+            f"/cli/builds/{urllib.parse.quote(manifest_hash_or_prefix, safe='')}/purge"
+        )
+
     def list_releases(self, app: str, environment: str | None = None) -> dict[str, Any]:
         return self._get("/cli/releases", {"app": app, "environment": environment})
 
@@ -399,6 +404,15 @@ class ApiClient:
         body: dict[str, Any] | None = {"environment": environment} if environment else None
         return self._json("POST", f"/app/{urllib.parse.quote(app, safe='')}/activate", body)
 
+    def purge_app(self, app: str) -> dict[str, Any]:
+        """Permanently purge orphaned app metadata for a partially-deleted app.
+
+        Hits ``DELETE /cli/apps/<slug>/purge``. The backend scopes the purge to
+        the API key's org and refuses to act while deployment rows still exist,
+        so ordinary deployed apps must use lifecycle commands first.
+        """
+        return self._delete(f"/cli/apps/{urllib.parse.quote(app, safe='')}/purge")
+
     def org_config(self) -> dict[str, Any]:
         return self._json("GET", "/org-config", None)
 

{urun_cli-0.5.2 → urun_cli-0.5.3}/src/urun/catalog.py

@@ -1,16 +1,23 @@
-"""Thin PostgREST client for the control-plane model catalog.
+"""Catalog client for the control-plane model catalog.
 
-``public.model_catalog`` is org-AGNOSTIC, anon-readable reference data published
-by a urun-infra migration (one row per ``(model_id, variant, gpu_spec)``; see
+``public.model_catalog`` is org-AGNOSTIC reference data published by a urun-infra
+migration (one row per ``(model_id, variant, gpu_spec)``; see
 ``urun-infra/catalog/CONTRACT.md``). ``urun serve catalog`` enumerates it and
 ``urun serve <id>[:<variant>]`` resolves a single row to deploy.
 
-CANONICAL PATH (no silent fallbacks — see CLAUDE.md): the catalog is read over
-PostgREST at the control-plane's ``/rest/v1/model_catalog`` endpoint. The base is
-derived from the SAME control-plane API URL the rest of the CLI uses (the origin
-of ``--api-url`` / ``URUN_API_URL`` / saved login, default ``api.urun.sh``), and
-PostgREST is reached with the public Supabase anon key. There is exactly ONE
-resolution for each input; a missing anon key FAILS HARD rather than guessing.
+DEFAULT PATH (no silent fallbacks — see CLAUDE.md): the catalog is read over the
+uRun API's ``/catalog`` edge function, authed with ONLY the user's API key
+(``Authorization: Bearer <api_key>`` — NO Supabase anon key). The base is the
+SAME control-plane API URL the rest of the CLI uses (``--api-url`` /
+``URUN_API_URL`` / saved login, default ``api.urun.sh``); the request GETs
+``<api_url>/catalog`` and the JSON body is ``{"rows": [ ...model_catalog rows... ]}``.
+Build this client with :meth:`CatalogClient.from_api`.
+
+DEPRECATED PATH: the old direct-PostgREST read at
+``/rest/v1/model_catalog`` with the public Supabase anon key
+(``apikey`` + ``Authorization: Bearer <anon>``, response a top-level JSON array)
+stays as an explicit opt-in fallback for callers that pass an anon key or a
+``--catalog-url``. There is exactly ONE resolution for each input.
 """
 
 from __future__ import annotations
@@ -549,12 +556,18 @@ def valid_skus_for_row(row: CatalogRow) -> list[str]:
 
 
 class CatalogClient:
-    """Reads ``public.model_catalog`` over PostgREST.
+    """Reads ``public.model_catalog`` over one of two transports.
 
-    ``base_url`` is the PostgREST base (``.../rest/v1``); ``anon_key`` is the
-    public Supabase anon key sent as the ``apikey`` header (the table grants
-    SELECT to ``anon``). Both are resolved by the CLI's single canonical path
-    (see :func:`urun.serve.resolve_catalog_client`).
+    DEFAULT (``mode="api"``, built via :meth:`from_api`): GET ``<api_url>/catalog``
+    with ONLY the user's API key (``Authorization: Bearer <api_key>`` — no
+    ``apikey`` header). The edge function returns ``{"rows": [ ...catalog rows... ]}``.
+
+    DEPRECATED (``mode="postgrest"``, the raw ``__init__``): GET the PostgREST base
+    (``.../rest/v1``) with the public Supabase anon key (``apikey`` + ``Bearer``
+    headers); the response is a top-level JSON array. Used only when a caller
+    explicitly opts in with an anon key or a ``--catalog-url``.
+
+    Both are resolved by :func:`urun.serve.resolve_catalog_client`.
     """
 
     def __init__(
@@ -565,21 +578,69 @@ class CatalogClient:
         backoff: BackoffPolicy = DEPLOY_BACKOFF,
         on_retry: Callable[[str], None] | None = None,
     ):
+        """Build a DEPRECATED PostgREST/anon-key client.
+
+        ``base_url`` is the PostgREST base (``.../rest/v1``); ``anon_key`` is the
+        public Supabase anon key. Prefer :meth:`from_api` (the default API-key
+        transport); this path is kept only as an explicit opt-in fallback.
+        """
         require_safe_url(base_url, "catalog URL")
         if not anon_key:
             raise UrunError("missing catalog anon key")
         self.base_url = base_url.rstrip("/")
         self.anon_key = anon_key
+        self.api_key: str | None = None
+        self._mode = "postgrest"
         self.timeout = timeout
         self.backoff = backoff
         self.on_retry = on_retry
 
+    @classmethod
+    def from_api(
+        cls,
+        api_url: str,
+        api_key: str,
+        timeout: float = 30.0,
+        backoff: BackoffPolicy = DEPLOY_BACKOFF,
+        on_retry: Callable[[str], None] | None = None,
+    ) -> CatalogClient:
+        """Build the DEFAULT API-key catalog client.
+
+        Targets ``<api_url rstrip '/'>/catalog`` and authenticates with ONLY the
+        user's API key (``Authorization: Bearer <api_key>``; no anon key). The
+        edge function returns ``{"rows": [ ...full model_catalog rows... ]}``.
+        """
+        base = (api_url or "").rstrip("/") + "/catalog"
+        require_safe_url(base, "catalog URL")
+        if not api_key:
+            raise UrunError("missing catalog API key")
+        self = cls.__new__(cls)
+        self.base_url = base
+        self.anon_key = ""
+        self.api_key = api_key
+        self._mode = "api"
+        self.timeout = timeout
+        self.backoff = backoff
+        self.on_retry = on_retry
+        return self
+
     def select_rows(self) -> list[CatalogRow]:
         """Select the full catalog, PK-ordered, as :class:`CatalogRow` objects.
 
-        Raises a clear, actionable error when the table is not seeded yet (it
-        ships via a urun-infra migration) instead of a raw PostgREST 404.
+        API mode reads the ``rows`` array from the ``{"rows": [...]}`` JSON object
+        the ``/catalog`` edge function returns; PostgREST mode reads a top-level
+        JSON array. Raises a clear, actionable error when the catalog is not
+        seeded yet (it ships via a urun-infra migration) instead of a raw 404.
         """
+        if self._mode == "api":
+            payload = self._get("")
+            if not isinstance(payload, dict):
+                raise UrunError("catalog response was not a JSON object with a 'rows' array")
+            rows = payload.get("rows")
+            if not isinstance(rows, list):
+                raise UrunError("catalog response 'rows' was not a JSON array")
+            return [parse_row(item) for item in rows]
+
         params = urllib.parse.urlencode(
             {"select": "*", "order": "model_id,variant,gpu_spec"}, safe=",:"
         )
@@ -588,17 +649,25 @@ class CatalogClient:
             raise UrunError("catalog response was not a JSON array")
         return [parse_row(item) for item in payload]
 
+    def _headers(self) -> dict[str, str]:
+        common = {
+            "Accept": "application/json",
+            "User-Agent": f"urun-cli/{__version__}",
+        }
+        if self._mode == "api":
+            return {**common, "Authorization": f"Bearer {self.api_key}"}
+        return {
+            **common,
+            "apikey": self.anon_key,
+            "Authorization": f"Bearer {self.anon_key}",
+        }
+
     def _get(self, path: str) -> Any:
         def attempt() -> bytes:
             req = urllib.request.Request(
                 self.base_url + path,
                 method="GET",
-                headers={
-                    "apikey": self.anon_key,
-                    "Authorization": f"Bearer {self.anon_key}",
-                    "Accept": "application/json",
-                    "User-Agent": f"urun-cli/{__version__}",
-                },
+                headers=self._headers(),
             )
             try:
                 with urllib.request.urlopen(req, timeout=self.timeout) as resp:
@@ -611,7 +680,7 @@ class CatalogClient:
                 attempt,
                 policy=self.backoff,
                 on_retry=self.on_retry,
-                description=f"GET {path}",
+                description=f"GET {self.base_url + path}",
             )
         except (urllib.error.URLError, TimeoutError) as exc:
             reason = getattr(exc, "reason", exc)

{urun_cli-0.5.2 → urun_cli-0.5.3}/src/urun/cli.py

@@ -9,6 +9,7 @@ import sys
 import urllib.parse
 import webbrowser
 from collections.abc import Callable, Sequence
+from contextlib import contextmanager, redirect_stderr, redirect_stdout
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
@@ -34,6 +35,7 @@ CONTROL_CHARS_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
 MAX_TABLE_CELL_WIDTH = 80
 MAX_DETAIL_CELL_WIDTH = 96
 DEFAULT_ENVIRONMENT = "main"
+DEFAULT_CONSOLE_URL = "https://app.urun.sh"
 ENVIRONMENT_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$")
 ENVIRONMENT_MESSAGE = (
     "environment name must be 2-32 lowercase letters, digits or hyphens, "
@@ -149,6 +151,8 @@ def main(argv: list[str] | None = None) -> int:
             return use_command(args)
         if args.command == "app":
             return app_command(args)
+        if args.command == "build":
+            return build_command(args)
         if args.command == "serve":
             from .serve import serve_command
 
@@ -172,8 +176,8 @@ def build_parser() -> argparse.ArgumentParser:
         "login",
         help="Save manually vended deploy credentials",
         description=(
-            "Save a manually vended URUN deploy API key. "
-            "Browser-based login is planned but not available in this CLI release."
+            "Save a manually vended URUN deploy API key. If no key is provided, "
+            "the CLI opens the console API keys page and prompts for the key."
         ),
     )
     add_login_args(login_parser)
@@ -309,6 +313,7 @@ def build_parser() -> argparse.ArgumentParser:
         add_api_args(p)
 
     add_app_parser(sub)
+    add_build_parser(sub)
     add_cli_parity_parsers(sub)
     from .serve import add_serve_parser
 
@@ -571,9 +576,7 @@ def add_open_use_parsers(sub: argparse._SubParsersAction) -> None:
     open_sub = open_parser.add_subparsers(dest="open_target")
     for target in ("billing", "git-connect"):
         p = open_sub.add_parser(target, help=f"Open {target}")
-        p.add_argument(
-            "--console-url", default=os.getenv("URUN_CONSOLE_URL", "https://app.urun.sh")
-        )
+        p.add_argument("--console-url", default=os.getenv("URUN_CONSOLE_URL", DEFAULT_CONSOLE_URL))
     use = sub.add_parser("use", help="Use a local default")
     use_sub = use.add_subparsers(dest="use_target")
     env = use_sub.add_parser("environment", help="Set default environment")
@@ -583,7 +586,7 @@ def add_open_use_parsers(sub: argparse._SubParsersAction) -> None:
 def add_app_parser(sub: argparse._SubParsersAction) -> None:
     app_parser = sub.add_parser(
         "app",
-        help="Manage a deployed app (status, scale, delete)",
+        help="Manage a deployed app (status, scale, delete, purge)",
         description=(
             "Manage the lifecycle of a single deployed app in the authenticated "
             "org. The app is addressed by its slug (the name shown under APP in "
@@ -674,6 +677,29 @@ def add_app_parser(sub: argparse._SubParsersAction) -> None:
     )
     add_api_args(delete_parser)
 
+    purge_parser = app_sub.add_parser(
+        "purge",
+        help="Permanently purge orphaned app metadata after a partial deletion",
+        description=(
+            "Permanently purge stale app metadata and capacity snapshots for an "
+            "app that no longer has a deployment row. This is not the normal "
+            "way to take an app down — use `urun app delete` first for deployed "
+            "apps. The backend refuses to purge apps that still have deployment "
+            "rows."
+        ),
+    )
+    purge_parser.add_argument("app", help="App slug (as shown by `urun list apps`)")
+    purge_parser.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help="Skip the interactive confirmation prompt",
+    )
+    purge_parser.add_argument(
+        "--json", action="store_true", help="Emit raw JSON instead of a formatted line"
+    )
+    add_api_args(purge_parser)
+
     activate_parser = app_sub.add_parser(
         "activate",
         help="Reverse a retire: bring a deleted app back online",
@@ -756,6 +782,36 @@ def add_config_parser(sub: argparse._SubParsersAction) -> None:
     set_parser.add_argument("value", help="Value to store")
 
 
+def add_build_parser(sub: argparse._SubParsersAction) -> None:
+    build_parser = sub.add_parser(
+        "build",
+        help="Manage build artifacts",
+        description="Manage build artifacts that are not represented by app lifecycle commands.",
+    )
+    build_sub = build_parser.add_subparsers(dest="build_command")
+    purge_parser = build_sub.add_parser(
+        "purge",
+        help="Permanently purge a failed build artifact",
+        description=(
+            "Delete a failed deployment status artifact from the authenticated "
+            "org. Pass the full 64-character manifest hash, or a unique 12+ "
+            "character prefix as shown in app/build listings. Only failed "
+            "artifacts can be purged."
+        ),
+    )
+    purge_parser.add_argument("manifest", help="Manifest hash or unique 12+ char prefix")
+    purge_parser.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help="Skip the interactive confirmation prompt",
+    )
+    purge_parser.add_argument(
+        "--json", action="store_true", help="Emit raw JSON instead of a formatted line"
+    )
+    add_api_args(purge_parser)
+
+
 def add_login_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--api-url",
@@ -763,7 +819,15 @@ def add_login_args(parser: argparse.ArgumentParser) -> None:
     )
     parser.add_argument(
         "--api-key",
-        help="Deploy API key; defaults to URUN_API_KEY, otherwise prompts interactively",
+        help=(
+            "Deploy API key; defaults to URUN_API_KEY, otherwise opens the console "
+            "and prompts interactively"
+        ),
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Print the API keys URL instead of opening a browser",
     )
 
 
@@ -822,8 +886,23 @@ def login(args: argparse.Namespace) -> int:
     api_key = args.api_key or os.getenv("URUN_API_KEY")
     if not api_key:
         if not sys.stdin.isatty():
-            raise UrunError("missing API key; pass --api-key or set URUN_API_KEY")
-        api_key = getpass.getpass("URUN API key: ").strip()
+            raise UrunError(
+                "missing API key; set URUN_API_KEY, pass --api-key, or run `urun login` "
+                "in an interactive terminal"
+            )
+        console_url = api_keys_console_url()
+        print("No URUN_API_KEY found.")
+        print("Create an API key in the urun console, then paste it here.")
+        print(f"Console URL: {console_url}")
+        if args.no_browser:
+            print("Browser launch skipped because --no-browser was passed.")
+        else:
+            opened = open_browser(console_url)
+            if opened:
+                print("Opened the console API keys page in your browser.")
+            else:
+                print("Could not open a browser automatically; open the Console URL above.")
+        api_key = getpass.getpass("Paste your urun API key: ").strip()
 
     validate_api_key(api_key)
     config = ApiClient(api_url, api_key).org_config()
@@ -846,6 +925,47 @@ def login(args: argparse.Namespace) -> int:
     return 0
 
 
+def api_keys_console_url() -> str:
+    console_url = os.getenv("URUN_CONSOLE_URL", DEFAULT_CONSOLE_URL)
+    url = console_url.rstrip("/") + "/settings/api-keys"
+    require_safe_url(url, "console URL")
+    return url
+
+
+def open_browser(url: str) -> bool:
+    """Open a URL without letting browser/desktop-launcher noise pollute the prompt."""
+    with silence_stdio_fds():
+        return webbrowser.open(url)
+
+
+@contextmanager
+def silence_stdio_fds():
+    """Temporarily send child-process stdout/stderr to /dev/null.
+
+    ``contextlib.redirect_stderr`` only swaps Python's ``sys.stderr`` object; GUI
+    launchers and browsers spawned by ``webbrowser.open`` write to the inherited
+    OS file descriptors. Redirect those descriptors briefly so GTK/browser
+    warnings do not appear in the middle of the API-key prompt.
+    """
+    saved_stdout = None
+    saved_stderr = None
+    try:
+        saved_stdout = os.dup(1)
+        saved_stderr = os.dup(2)
+        with open(os.devnull, "w", encoding="utf-8") as devnull:
+            os.dup2(devnull.fileno(), 1)
+            os.dup2(devnull.fileno(), 2)
+            with redirect_stdout(devnull), redirect_stderr(devnull):
+                yield
+    finally:
+        if saved_stdout is not None:
+            os.dup2(saved_stdout, 1)
+            os.close(saved_stdout)
+        if saved_stderr is not None:
+            os.dup2(saved_stderr, 2)
+            os.close(saved_stderr)
+
+
 def org(args: argparse.Namespace) -> int:
     # `urun org` and `urun org id` both print just the org id. There is no other
     # `org` subcommand, so a bare `org` defaults to `id`.
@@ -874,17 +994,21 @@ def config_command(args: argparse.Namespace) -> int:
         )
         return 0
     if command == "set" and key == "default-environment":
-        environment = validate_environment(args.value)
-        config = load_config()
-        config["default-environment"] = environment
-        path = save_config(config)
-        print(f"default-environment = {environment}")
-        print(f"Config: {path}")
-        return 0
+        return _set_default_environment(args.value)
     print("usage: urun config {get,set} default-environment [value]", file=sys.stderr)
     return 2
 
 
+def _set_default_environment(value: str) -> int:
+    environment = validate_environment(value)
+    config = load_config()
+    config["default-environment"] = environment
+    path = save_config(config)
+    print(f"default-environment = {environment}")
+    print(f"Config: {path}")
+    return 0
+
+
 def trust_jwk(args: argparse.Namespace) -> int:
     jwks_url = trust_jwk_url(args)
     validate_jwks_url(jwks_url, allow_insecure=args.allow_insecure_jwks_url)
@@ -1473,13 +1597,7 @@ def use_command(args: argparse.Namespace) -> int:
     if getattr(args, "use_target", None) != "environment":
         print("usage: urun use environment <env>", file=sys.stderr)
         return 2
-    environment = validate_environment(args.environment)
-    config = load_config()
-    config["default-environment"] = environment
-    path = save_config(config)
-    print(f"default-environment = {environment}")
-    print(f"Config: {path}")
-    return 0
+    return _set_default_environment(args.environment)
 
 
 def list_apps(args: argparse.Namespace) -> int:
@@ -1490,6 +1608,7 @@ def list_apps(args: argparse.Namespace) -> int:
         empty_message="No apps found.",
         headers=("APP", "ENV", "FUNCTION", "COMPUTE", "STATUS", "RELEASE", "DETAIL"),
         rows=lambda apps: [_app_row(a) for a in apps],
+        enrich=enrich_app_row,
     )
 
 
@@ -1501,6 +1620,7 @@ def _render_list(
     empty_message: str,
     headers: tuple[str, ...],
     rows: Callable[[list[dict[str, Any]]], Sequence[tuple[str, ...]]],
+    enrich: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
 ) -> int:
     api_url, api_key = resolve_api_credentials(args)
     client = ApiClient(api_url, api_key)
@@ -1509,16 +1629,20 @@ def _render_list(
     if not isinstance(items, list):
         raise UrunError(f"server returned invalid {key} payload")
 
+    dict_items = _validate_list_items(items, key)
+    enriched_items = [enrich(item) if enrich else dict(item) for item in dict_items]
+    canonical = dict(response)
+    canonical[key] = enriched_items
+
     if getattr(args, "json", False):
-        print(json.dumps({key: items}, indent=2, sort_keys=True))
+        print(json.dumps(canonical, indent=2, sort_keys=True))
         return 0
 
-    if not items:
+    if not enriched_items:
         print(empty_message)
         return 0
 
-    dict_items = _validate_list_items(items, key)
-    _print_table(headers, list(rows(dict_items)))
+    _print_table(headers, list(rows(enriched_items)))
     return 0
 
 
@@ -1537,12 +1661,48 @@ def app_command(args: argparse.Namespace) -> int:
         return app_scale(args)
     if command in {"delete", "rm"}:
         return app_delete(args)
+    if command == "purge":
+        return app_purge(args)
     if command == "activate":
         return app_activate(args)
-    print("usage: urun app {status,scale,delete,activate} <app> [options]", file=sys.stderr)
+    print("usage: urun app {status,scale,delete,purge,activate} <app> [options]", file=sys.stderr)
     return 2
 
 
+def build_command(args: argparse.Namespace) -> int:
+    command = getattr(args, "build_command", None)
+    if command == "purge":
+        return build_purge(args)
+    print("usage: urun build {purge} <manifest-hash-or-prefix> [options]", file=sys.stderr)
+    return 2
+
+
+def build_purge(args: argparse.Namespace) -> int:
+    if len(args.manifest) < 12:
+        raise UrunError(
+            "manifest must be a full 64-character hash or a unique 12+ character prefix"
+        )
+    if not getattr(args, "yes", False) and not _confirm_action(
+        f"Permanently purge failed build artifact '{args.manifest}'? This cannot be undone."
+    ):
+        print("Aborted.")
+        return 1
+    response = _client(args).purge_build(args.manifest)
+    if getattr(args, "json", False):
+        _print_json(response)
+        return 0
+    build = response.get("build")
+    if not isinstance(build, dict):
+        raise UrunError("server returned invalid build payload")
+    manifest = _short_hash(build.get("manifest_hash"))
+    app = _coalesce_str(build.get("app_slug"), "-")
+    environment = _coalesce_str(build.get("environment"), "-")
+    print(f"Purged failed build artifact {manifest}.")
+    print(f"App: {app}")
+    print(f"Environment: {environment}")
+    return 0
+
+
 def _app_payload(response: dict[str, Any]) -> dict[str, Any]:
     app = response.get("app")
     if not isinstance(app, dict):
@@ -1554,21 +1714,19 @@ def app_status(args: argparse.Namespace) -> int:
     api_url, api_key = resolve_api_credentials(args)
     environment = resolve_environment(args)
     client = ApiClient(api_url, api_key)
-    response = client.app_status(args.app, environment=environment)
+    response = build_app_status_payload(client, args.app, environment=environment)
     if getattr(args, "json", False):
         print(json.dumps(response, indent=2, sort_keys=True))
         return 0
     app = _app_payload(response)
-    display_status = _derive_display_status(app)
-    detail = _derive_detail(app, display_status)
     fields = [
         ("App", _coalesce_str(app.get("app_slug"), args.app)),
         ("Name", _coalesce_str(app.get("app_name"), "-")),
         ("Environment", _coalesce_str(app.get("environment"), "-")),
         ("App status", _coalesce_str(app.get("app_status"), "-")),
         ("Deployment", _coalesce_str(app.get("deployment_status"), "(not deployed)")),
-        ("Status", display_status),
-        ("Detail", detail),
+        ("Status", _coalesce_str(app.get("status"), _DISPLAY_UNKNOWN)),
+        ("Detail", _coalesce_str(app.get("detail"), "-")),
         ("Desired replicas", _int_str(app.get("desired_replicas"))),
         ("Function", _coalesce_str(app.get("function_name"), app.get("default_function"), "-")),
         ("Compute", _coalesce_str(app.get("compute_shape"), "-")),
@@ -1582,6 +1740,139 @@ def app_status(args: argparse.Namespace) -> int:
     return 0
 
 
+def build_app_status_payload(
+    client: ApiClient, app_slug: str, *, environment: str
+) -> dict[str, Any]:
+    """Return the canonical app-status payload used by JSON and human output.
+
+    The app-detail endpoint currently has richer identity/deployment fields than
+    the apps listing, while the apps listing has the readiness/capacity fields
+    needed to decide whether an active deployment is actually serving. Compose
+    those backend responses once, then render every output mode from the result.
+    """
+    response = client.app_status(app_slug, environment=environment)
+    app = _app_payload(response)
+    warnings = (
+        list(response.get("warnings") or []) if isinstance(response.get("warnings"), list) else []
+    )
+    if not _app_status_has_readiness_detail(app):
+        try:
+            list_row = _matching_app_list_row(client, app, app_slug, environment)
+        except UrunError as exc:
+            warnings.append(
+                {
+                    "code": "app_readiness_enrichment_unavailable",
+                    "message": str(exc),
+                }
+            )
+        else:
+            if list_row:
+                app = _merge_app_status_row(app, list_row)
+    app = enrich_app_row(app)
+    canonical = dict(response)
+    canonical["app"] = app
+    if warnings:
+        canonical["warnings"] = warnings
+    return canonical
+
+
+def _app_status_has_readiness_detail(app: dict[str, Any]) -> bool:
+    build = _coalesce_str(app.get("build_status"), "").lower()
+    if build in {"queued", "building", "failed"}:
+        return True
+    deployment = _coalesce_str(app.get("deployment_status"), "").lower()
+    if deployment in {"paused", "failed"}:
+        return True
+    if deployment != "active":
+        return False
+    if app.get("function_ready") is True:
+        return _is_non_bool_int(app.get("ready_gpu_units")) and _is_non_bool_int(
+            app.get("allocated_gpu_units")
+        )
+    if app.get("function_ready") is False:
+        return "ready_reason" in app
+    return False
+
+
+def _matching_app_list_row(
+    client: ApiClient, app: dict[str, Any], app_slug: str, environment: str
+) -> dict[str, Any] | None:
+    apps_response = client.list_apps()
+    apps = apps_response.get("apps") or []
+    if not isinstance(apps, list):
+        raise UrunError("server returned invalid apps payload")
+    app_id = _coalesce_str(app.get("app_id"))
+    current_release_id = _coalesce_str(app.get("current_release_id"))
+    manifest_hash = _coalesce_str(app.get("manifest_hash"), app.get("release_version"))
+    function_name = _coalesce_str(app.get("function_name"), app.get("default_function"))
+    compute_shape = _coalesce_str(app.get("compute_shape"))
+    slug = _coalesce_str(app.get("app_slug"), app_slug)
+
+    def score(candidate: dict[str, Any]) -> int:
+        candidate_env = _coalesce_str(candidate.get("environment"), DEFAULT_ENVIRONMENT)
+        if candidate_env != environment:
+            return -1
+        candidate_slug = _coalesce_str(candidate.get("app_slug"), candidate.get("app_name"))
+        if candidate_slug and candidate_slug != slug:
+            return -1
+        candidate_hash = _coalesce_str(
+            candidate.get("manifest_hash"), candidate.get("release_version")
+        )
+        if manifest_hash and candidate_hash and candidate_hash != manifest_hash:
+            return -1
+        if function_name and candidate.get("function_name") not in {None, function_name}:
+            return -1
+        if compute_shape and candidate.get("compute_shape") not in {None, compute_shape}:
+            return -1
+        value = 1
+        if app_id and candidate.get("app_id") == app_id:
+            value += 8
+        if current_release_id and candidate.get("release_id") == current_release_id:
+            value += 4
+        if manifest_hash and candidate_hash == manifest_hash:
+            value += 4
+        if function_name and candidate.get("function_name") == function_name:
+            value += 2
+        if compute_shape and candidate.get("compute_shape") == compute_shape:
+            value += 2
+        return value
+
+    best: tuple[int, dict[str, Any]] | None = None
+    for candidate in apps:
+        if not isinstance(candidate, dict):
+            raise UrunError("server returned invalid apps payload")
+        candidate_score = score(candidate)
+        if candidate_score < 0:
+            continue
+        if best is None or candidate_score > best[0]:
+            best = (candidate_score, candidate)
+    return dict(best[1]) if best else None
+
+
+def _merge_app_status_row(app: dict[str, Any], list_row: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(app)
+    for key, value in list_row.items():
+        if key in {"app_name", "app_slug", "environment"}:
+            merged.setdefault(key, value)
+        elif key not in merged or merged[key] is None:
+            merged[key] = value
+        elif (
+            key
+            in {
+                "build_status",
+                "function_ready",
+                "ready_reason",
+                "ready_gpu_units",
+                "allocated_gpu_units",
+                "queued_requests",
+                "active_sessions",
+            }
+            and value is not None
+        ):
+            merged[key] = value
+    return merged
+
+
 def app_scale(args: argparse.Namespace) -> int:
     if args.replicas < 0:
         raise UrunError("--replicas must be >= 0")
@@ -1621,6 +1912,29 @@ def app_delete(args: argparse.Namespace) -> int:
     return 0
 
 
+def app_purge(args: argparse.Namespace) -> int:
+    if not getattr(args, "yes", False) and not _confirm_action(
+        f"Permanently purge orphaned app state for '{args.app}'? This cannot be undone."
+    ):
+        print("Aborted.")
+        return 1
+    api_url, api_key = resolve_api_credentials(args)
+    client = ApiClient(api_url, api_key)
+    response = client.purge_app(args.app)
+    if getattr(args, "json", False):
+        print(json.dumps(response, indent=2, sort_keys=True))
+        return 0
+    app = _app_payload(response)
+    slug = _coalesce_str(app.get("app_slug"), args.app)
+    print(f"Purged orphaned app state for {slug}.")
+    deleted = app.get("deleted")
+    if not isinstance(deleted, dict):
+        raise UrunError("server returned invalid app purge payload")
+    for key in sorted(deleted):
+        print(f"  {key}: {_int_str(deleted.get(key))}")
+    return 0
+
+
 def app_activate(args: argparse.Namespace) -> int:
     api_url, api_key = resolve_api_credentials(args)
     environment = resolve_environment(args)
@@ -1868,8 +2182,8 @@ def _app_row(d: dict[str, Any]) -> tuple[str, str, str, str, str, str, str]:
     app, function, compute = _resource_identity(d)
     environment = _coalesce_str(d.get("environment"), "-")
     release = _short_hash(d.get("manifest_hash") or d.get("release_version"))
-    status = _derive_display_status(d)
-    detail = _derive_detail(d, status)
+    status = _coalesce_str(d.get("status"), _DISPLAY_UNKNOWN)
+    detail = _coalesce_str(d.get("detail"), "-")
     return (app, environment, function, compute, status, release, detail)
 
 
@@ -1894,7 +2208,11 @@ def _derive_display_status(d: dict[str, Any]) -> str:
     if promotion == "failed":
         return _DISPLAY_FAILED
     if promotion == "active":
-        return _DISPLAY_READY if d.get("function_ready") else _DISPLAY_PENDING
+        if d.get("function_ready") is True:
+            return _DISPLAY_READY
+        if d.get("function_ready") is False:
+            return _DISPLAY_PENDING
+        return _DISPLAY_UNKNOWN
     return _DISPLAY_UNKNOWN
 
 
@@ -1904,7 +2222,7 @@ def _derive_detail(d: dict[str, Any], status: str) -> str:
     if status == _DISPLAY_FAILED:
         return _coalesce_str(_failure_summary(d), d.get("ready_reason"), "Build failed")
     if status == _DISPLAY_PENDING:
-        return _coalesce_str(d.get("ready_reason"), "no_capacity_snapshot")
+        return _coalesce_str(d.get("ready_reason"), "-")
     if status == _DISPLAY_READY:
         ready = d.get("ready_gpu_units")
         allocated = d.get("allocated_gpu_units")
@@ -1914,6 +2232,14 @@ def _derive_detail(d: dict[str, Any], status: str) -> str:
     return "-"
 
 
+def enrich_app_row(row: dict[str, Any]) -> dict[str, Any]:
+    enriched = dict(row)
+    status = _derive_display_status(enriched)
+    enriched["status"] = status
+    enriched["detail"] = _derive_detail(enriched, status)
+    return enriched
+
+
 def _failure_summary(source: Any) -> str:
     if not isinstance(source, dict):
         return ""
@@ -1948,6 +2274,7 @@ def list_sessions(args: argparse.Namespace) -> int:
         # Server returns newest-first to take the LIMIT cleanly; reverse so the
         # newest rows appear at the bottom of the table (tail-friendly).
         rows=lambda sessions: [_session_row(s, now) for s in reversed(sessions)],
+        enrich=lambda session: enrich_session_row(session, now),
     )
 
 
@@ -1955,13 +2282,23 @@ def _session_row(s: dict[str, Any], now: datetime) -> tuple[str, str, str, str,
     sid = _short_hash(s.get("id"))
     app, function, shape = _resource_identity(s)
     started = _format_iso_minutes(s.get("allocated_at") or s.get("created_at"))
-    duration = _format_duration(_session_duration_seconds(s, now))
-    raw_status = _coalesce_str(s.get("status"), "").lower()
-    state = _SESSION_STATE_DISPLAY.get(raw_status, raw_status or _DISPLAY_UNKNOWN)
-    detail = _coalesce_str(s.get("close_reason"), "-")
+    duration = _coalesce_str(s.get("duration"), "-")
+    state = _coalesce_str(s.get("state"), _DISPLAY_UNKNOWN)
+    detail = _coalesce_str(s.get("detail"), "-")
     return (sid, app, function, shape, started, duration, state, detail)
 
 
+def enrich_session_row(s: dict[str, Any], now: datetime) -> dict[str, Any]:
+    enriched = dict(s)
+    duration_seconds = _session_duration_seconds(enriched, now)
+    raw_status = _coalesce_str(enriched.get("status"), "").lower()
+    enriched["state"] = _SESSION_STATE_DISPLAY.get(raw_status, raw_status or _DISPLAY_UNKNOWN)
+    enriched["detail"] = _coalesce_str(enriched.get("close_reason"), "-")
+    enriched["duration_seconds"] = int(duration_seconds) if duration_seconds is not None else None
+    enriched["duration"] = _format_duration(duration_seconds)
+    return enriched
+
+
 def _session_duration_seconds(s: dict[str, Any], now: datetime) -> float | None:
     start = _parse_iso(s.get("allocated_at")) or _parse_iso(s.get("created_at"))
     if start is None:
@@ -2010,18 +2347,45 @@ def list_compute(args: argparse.Namespace) -> int:
         key="compute",
         fetch=lambda client: client.list_compute(limit=getattr(args, "limit", None)),
         empty_message="No compute is currently provisioned.",
-        headers=("APP", "FUNCTION", "SHAPE", "INSTANCES", "GPU UNITS", "SESSIONS", "AGE"),
+        headers=(
+            "APP",
+            "FUNCTION",
+            "SHAPE",
+            "INSTANCES",
+            "GPU UNITS",
+            "SESSIONS",
+            "AGE",
+            "REASON",
+        ),
         rows=lambda slices: [_compute_row(s, now) for s in slices],
+        enrich=lambda compute: enrich_compute_row(compute, now),
     )
 
 
-def _compute_row(s: dict[str, Any], now: datetime) -> tuple[str, str, str, str, str, str, str]:
+def _compute_row(s: dict[str, Any], now: datetime) -> tuple[str, str, str, str, str, str, str, str]:
     app, function, shape = _resource_identity(s)
-    instances = _format_pair(s.get("instances_allocated"), s.get("instances_ready"))
-    units = _format_pair(s.get("gpu_units_allocated"), s.get("gpu_units_ready"))
-    sessions = _format_count(s.get("active_sessions"))
-    age = _format_age_seconds(_age_seconds(s.get("snapshot_observed_at"), now))
-    return (app, function, shape, instances, units, sessions, age)
+    instances = _coalesce_str(s.get("instances"), "-")
+    units = _coalesce_str(s.get("gpu_units"), "-")
+    sessions = _coalesce_str(s.get("sessions"), "-")
+    age = _coalesce_str(s.get("age"), "-")
+    reason = _coalesce_str(s.get("reason"), s.get("ready_reason"), "-")
+    return (app, function, shape, instances, units, sessions, age, reason)
+
+
+def enrich_compute_row(s: dict[str, Any], now: datetime) -> dict[str, Any]:
+    enriched = dict(s)
+    age_seconds = _age_seconds(enriched.get("snapshot_observed_at"), now)
+    enriched["instances"] = _format_pair(
+        enriched.get("instances_allocated"), enriched.get("instances_ready")
+    )
+    enriched["gpu_units"] = _format_pair(
+        enriched.get("gpu_units_allocated"), enriched.get("gpu_units_ready")
+    )
+    enriched["sessions"] = _format_count(enriched.get("active_sessions"))
+    enriched["age_seconds"] = int(age_seconds) if age_seconds is not None else None
+    enriched["age"] = _format_age_seconds(age_seconds)
+    enriched["reason"] = _coalesce_str(enriched.get("ready_reason"), "-")
+    return enriched
 
 
 def _format_pair(numerator: Any, denominator: Any) -> str:
@@ -2053,8 +2417,8 @@ def _age_seconds(observed_at: Any, now: datetime) -> float | None:
 
 def _format_age_seconds(seconds: float | None) -> str:
     # Compact age string for snapshot freshness. The view-side staleness
-    # threshold (10 min) is reflected in ready_reason for machine consumers;
-    # this column is just a human "how fresh is the data" signal.
+    # threshold (10 min) is reflected in ready_reason, which is now surfaced as
+    # the human REASON column; AGE stays a human "how fresh is the data" signal.
     if seconds is None:
         return "-"
     total = int(seconds)

{urun_cli-0.5.2 → urun_cli-0.5.3}/src/urun/manifest.py

@@ -65,9 +65,23 @@ def canonical_json(data: dict[str, Any]) -> bytes:
     )
 
 
+# Manifest fields that are PURELY informational metadata — they describe WHEN /
+# by WHICH client a deploy happened, not WHAT is being deployed. They MUST be
+# excluded from ``manifest_hash`` so the hash is a true content address: two
+# deploys of an identical source tree produce an identical hash (and therefore
+# the SAME server-side release — no new ``app_releases`` row, no repoint, no pod
+# roll). Folding ``created_at`` (a per-deploy wall-clock timestamp) into the hash
+# was the root cause of no-change redeploys minting a fresh release every time
+# and rolling the runtime pod (~7 min not-ready -> "0 candidates" -> no frames).
+# ``client_version`` is excluded for the same reason: a CLI upgrade must not roll
+# every pod when the deployed content is byte-identical.
+_NON_CONTENT_MANIFEST_FIELDS = ("manifest_hash", "created_at", "client_version")
+
+
 def manifest_hash(manifest_without_hash: dict[str, Any]) -> str:
     data = dict(manifest_without_hash)
-    data.pop("manifest_hash", None)
+    for field in _NON_CONTENT_MANIFEST_FIELDS:
+        data.pop(field, None)
     return hashlib.sha256(canonical_json(data)).hexdigest()
 
 

{urun_cli-0.5.2 → urun_cli-0.5.3}/src/urun/serve.py

@@ -25,8 +25,11 @@ deployed by this path (its deletion is a follow-up; other lanes still reference
 A user who already has a local ``_serve/app.py`` can point ``--entrypoint`` at it;
 that app is deployed in place (no shim, no per-deploy env).
 
-CANONICAL PATH (CLAUDE.md): one PostgREST base (control-plane API origin +
-``/rest/v1``) and one anon key resolution; missing inputs FAIL HARD.
+CANONICAL PATH (CLAUDE.md): the catalog is read over the uRun API's ``/catalog``
+endpoint using ONLY the user's API key (``<api_url>/catalog`` with
+``Authorization: Bearer <api_key>``; the body is ``{"rows": [...]}``). The old
+direct-PostgREST read with a Supabase anon key is a DEPRECATED opt-in fallback
+(``--anon-key`` / ``URUN_CATALOG_ANON_KEY`` / ``--catalog-url``).
 """
 
 from __future__ import annotations
@@ -125,14 +128,18 @@ def _add_catalog_resolution_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--catalog-url",
         help=(
-            "PostgREST base for the catalog (default: the control-plane API origin "
-            f"+ {POSTGREST_PREFIX}, or {CATALOG_URL_ENV})"
+            "DEPRECATED: PostgREST base for the catalog (e.g. the control-plane API "
+            f"origin + {POSTGREST_PREFIX}, or {CATALOG_URL_ENV}). The default reads the "
+            "uRun API /catalog endpoint with your API key; only set this to opt into "
+            "the legacy direct-PostgREST read."
         ),
     )
     parser.add_argument(
         "--anon-key",
         help=(
-            f"Supabase anon key for the public catalog read (default: {' / '.join(ANON_KEY_ENVS)})"
+            "DEPRECATED: Supabase anon key for the legacy direct-PostgREST catalog read "
+            f"(or {' / '.join(ANON_KEY_ENVS)}). The default reads the uRun API /catalog "
+            "endpoint with your API key — no anon key needed."
         ),
     )
 
@@ -415,28 +422,43 @@ def _render_deps_literal(python_deps: list[str]) -> str:
 def resolve_catalog_client(args: argparse.Namespace) -> CatalogClient:
     """Build the catalog client by the SINGLE canonical resolution.
 
-    Base: ``--catalog-url`` -> ``URUN_CATALOG_URL`` -> the control-plane API
-    origin + ``/rest/v1`` (same host the CLI already uses). Anon key:
-    ``--anon-key`` -> ``URUN_CATALOG_ANON_KEY`` -> ``URUN_SUPABASE_ANON_KEY``. A
-    missing anon key FAILS HARD (no guessing, no silent fallback).
+    DEFAULT (needs ONLY the API key): when no anon key (``--anon-key`` /
+    ``URUN_CATALOG_ANON_KEY`` / ``URUN_SUPABASE_ANON_KEY``) AND no catalog URL
+    (``--catalog-url`` / ``URUN_CATALOG_URL``) is given, resolve the API URL +
+    API key the rest of the CLI uses and return an API-key client that GETs
+    ``<api_url>/catalog`` with ``Authorization: Bearer <api_key>``.
+
+    DEPRECATED opt-in (PostgREST + anon key): if an anon key OR a ``--catalog-url``
+    IS explicitly provided, fall back to the legacy direct-PostgREST read. Base:
+    ``--catalog-url`` -> ``URUN_CATALOG_URL`` -> the control-plane API origin +
+    ``/rest/v1``. Anon key: ``--anon-key`` -> ``URUN_CATALOG_ANON_KEY`` ->
+    ``URUN_SUPABASE_ANON_KEY``. A ``--catalog-url`` without an anon key FAILS HARD.
     """
     from .cli import resolve_api_credentials
 
-    base = getattr(args, "catalog_url", None) or os.getenv(CATALOG_URL_ENV)
-    if not base:
-        api_url, _ = resolve_api_credentials(args)
-        base = _postgrest_base_from_api_url(api_url)
-
+    explicit_url = getattr(args, "catalog_url", None) or os.getenv(CATALOG_URL_ENV)
     anon_key = getattr(args, "anon_key", None)
     if not anon_key:
         for env in ANON_KEY_ENVS:
             anon_key = os.getenv(env)
             if anon_key:
                 break
+
+    # DEFAULT: no explicit PostgREST inputs -> read the API /catalog with the API key.
+    if not explicit_url and not anon_key:
+        api_url, api_key = resolve_api_credentials(args)
+        return CatalogClient.from_api(api_url, api_key)
+
+    # DEPRECATED opt-in: explicit anon key and/or --catalog-url -> direct PostgREST.
+    base = explicit_url
+    if not base:
+        api_url, _ = resolve_api_credentials(args)
+        base = _postgrest_base_from_api_url(api_url)
     if not anon_key:
         raise UrunError(
-            "missing Supabase anon key for the catalog read; pass --anon-key or set "
-            + " / ".join(ANON_KEY_ENVS)
+            "missing Supabase anon key for the deprecated PostgREST catalog read; pass "
+            "--anon-key or set " + " / ".join(ANON_KEY_ENVS) + " (or omit --catalog-url "
+            "to use the default uRun API /catalog read with your API key)"
         )
     return CatalogClient(base, anon_key)