withcache 0.7.0__tar.gz → 0.7.2__tar.gz

{withcache-0.7.0 → withcache-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: withcache
-Version: 0.7.0
+Version: 0.7.2
 Summary: Operator-curated, URL-keyed artifact cache for a small lab (CUDA/ROCm/DOCA/firmware)
 Project-URL: Homepage, https://github.com/safl/withcache
 Author-email: "Simon A. F. Lund" <safl@safl.dk>

{withcache-0.7.0 → withcache-0.7.2}/shim/build.zig.zon

@@ -2,7 +2,7 @@
     .name = .withcache_shim,
     // Zig requires a literal here; keep it in lockstep with the project's
     // single source (src/withcache/__init__.py) via `make bump` / `make version-check`.
-    .version = "0.7.0",
+    .version = "0.7.2",
     .fingerprint = 0xd7d96c5ed212ccaa,
     .minimum_zig_version = "0.16.0",
     .paths = .{

{withcache-0.7.0 → withcache-0.7.2}/src/withcache/__init__.py

@@ -17,6 +17,6 @@ All modules are stdlib-only and self-contained.
 from . import oras
 from .client import blob_url, cache_base, is_cached, serve_url
 
-__version__ = "0.7.0"
+__version__ = "0.7.2"
 
 __all__ = ["__version__", "blob_url", "cache_base", "is_cached", "oras", "serve_url"]

{withcache-0.7.0 → withcache-0.7.2}/src/withcache/server.py

@@ -152,6 +152,30 @@ def resolve_secret(data_dir: str) -> bytes:
 DEFAULT_CATALOG_URL = "https://github.com/safl/nosi/releases/latest/download/catalog.toml"
 
 
+def _serialise_catalog(entries: list[dict[str, Any]]) -> bytes:
+    """Serialise a list of catalog entries back to TOML bytes matching the
+    nosi ``version = 1`` + ``[[images]]`` schema. Stdlib-only, no
+    ``tomli_w`` dep: the schema is flat so a hand-rolled emitter is
+    safer than pulling in a write library. Only known scalar keys are
+    emitted; unknown keys are dropped (silently) so an operator-added
+    row can't smuggle arbitrary TOML through."""
+    out: list[str] = ["version = 1", ""]
+    for e in entries:
+        out.append("[[images]]")
+        for key in ("name", "src", "format", "arch", "sha256"):
+            val = e.get(key)
+            if val is None or val == "":
+                continue
+            # Escape backslashes + quotes then wrap in double quotes.
+            escaped = str(val).replace("\\", "\\\\").replace('"', '\\"')
+            out.append(f'{key} = "{escaped}"')
+        size = e.get("size_bytes")
+        if isinstance(size, int):
+            out.append(f"size_bytes = {size}")
+        out.append("")
+    return "\n".join(out).encode("utf-8")
+
+
 @dataclass
 class CatalogState:
     """Live state of the fetched image catalog.
@@ -167,20 +191,40 @@ class CatalogState:
     so a restart doesn't wipe the last known good catalog and the
     same file can be re-served verbatim to consumers on a future
     ``GET /catalog.toml`` route.
+
+    ``env_url`` records the value pinned via ``$WITHCACHE_CATALOG_URL``
+    (empty if unset). The operator can override the effective URL at
+    runtime via ``POST /admin/catalog_set_url``; the override is
+    persisted to ``<data_dir>/catalog_url`` and wins over the built-in
+    default, but the env var still wins over the operator override so
+    an operator can't silently unblock a locked-down deploy.
     """
 
     url: str
     persist_path: str
+    env_url: str = ""
+    url_override_path: str = ""
     entries: list[dict[str, Any]] = field(default_factory=list)
     fetched_at: str = ""
     last_error: str = ""
+    last_info: str = ""
     _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
 
     def load_persisted(self) -> None:
         """Best-effort: seed ``entries`` + ``fetched_at`` from the on-disk
-        ``catalog.toml`` if it exists. Never raises; a corrupt or missing
-        file leaves the state empty so the operator sees the "not
-        fetched yet" hint in the dashboard."""
+        ``catalog.toml`` if it exists. Also loads the operator URL
+        override from ``<data_dir>/catalog_url`` when the env var is
+        not set. Never raises; a corrupt or missing file leaves the
+        state empty so the operator sees the "not fetched yet" hint
+        in the dashboard."""
+        if self.url_override_path and os.path.isfile(self.url_override_path) and not self.env_url:
+            try:
+                with open(self.url_override_path, encoding="utf-8") as f:
+                    override = f.read().strip()
+                if override:
+                    self.url = override
+            except OSError:
+                pass
         if not os.path.isfile(self.persist_path):
             return
         try:
@@ -210,13 +254,11 @@ class CatalogState:
                 entries = list(parsed.get("images") or [])
                 # Atomic write: tempfile + rename so a crash mid-write
                 # never leaves a half-written catalog.toml.
-                tmp = self.persist_path + ".tmp"
-                with open(tmp, "wb") as f:
-                    f.write(raw)
-                os.replace(tmp, self.persist_path)
+                self._persist_bytes(raw)
                 self.entries = entries
                 self.fetched_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
                 self.last_error = ""
+                self.last_info = f"fetched {len(entries)} entries from {self.url}"
             except (
                 urllib.error.URLError,
                 OSError,
@@ -226,6 +268,109 @@ class CatalogState:
             ) as e:
                 self.last_error = str(e)
 
+    def set_url_override(self, new_url: str) -> tuple[bool, str]:
+        """Persist an operator-set URL override to
+        ``<data_dir>/catalog_url``. Env-var pin wins: if
+        ``$WITHCACHE_CATALOG_URL`` is set, the override is rejected
+        so a locked-down deploy stays locked down. Returns
+        ``(ok, message)`` for the UI to surface."""
+        if self.env_url:
+            return False, "env WITHCACHE_CATALOG_URL is pinned; unset it to allow overrides"
+        candidate = new_url.strip()
+        if not candidate:
+            return False, "url is empty"
+        if not candidate.startswith(("http://", "https://")):
+            return False, "url must start with http:// or https://"
+        with self._lock:
+            try:
+                if self.url_override_path:
+                    tmp = self.url_override_path + ".tmp"
+                    with open(tmp, "w", encoding="utf-8") as f:
+                        f.write(candidate + "\n")
+                    os.replace(tmp, self.url_override_path)
+                self.url = candidate
+            except OSError as e:
+                return False, str(e)
+        return True, f"catalog url set to {candidate}"
+
+    def replace_from_bytes(self, raw: bytes, *, source_label: str) -> tuple[bool, str]:
+        """Validate + persist an operator-supplied ``catalog.toml``
+        payload (from an upload). On success the in-memory ``entries``
+        are refreshed and ``last_info`` records the source. On
+        validation failure nothing on disk is touched."""
+        try:
+            parsed = tomllib.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, tomllib.TOMLDecodeError) as e:
+            return False, f"not a valid TOML file: {e}"
+        entries = list(parsed.get("images") or [])
+        with self._lock:
+            try:
+                self._persist_bytes(raw)
+            except OSError as e:
+                return False, str(e)
+            self.entries = entries
+            self.fetched_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+            self.last_error = ""
+            self.last_info = f"loaded {len(entries)} entries from {source_label}"
+        return True, self.last_info
+
+    def add_entry(self, entry: dict[str, Any]) -> tuple[bool, str]:
+        """Append a single ``[[images]]`` row to the persisted catalog
+        and refresh the in-memory list. ``entry`` must have at least
+        ``name`` and ``src``. Duplicate ``name`` replaces the existing
+        row (matches how ``bty-web``'s catalog-import handled dupes)."""
+        name = str(entry.get("name") or "").strip()
+        src = str(entry.get("src") or "").strip()
+        if not name:
+            return False, "name is required"
+        if not src:
+            return False, "src is required"
+        clean: dict[str, Any] = {"name": name, "src": src}
+        for key in ("format", "arch", "sha256"):
+            val = entry.get(key)
+            if isinstance(val, str) and val.strip():
+                clean[key] = val.strip()
+        with self._lock:
+            new_entries = [e for e in self.entries if str(e.get("name") or "") != name]
+            new_entries.append(clean)
+            raw = _serialise_catalog(new_entries)
+            try:
+                self._persist_bytes(raw)
+            except OSError as e:
+                return False, str(e)
+            self.entries = new_entries
+            self.last_error = ""
+            self.last_info = f"added entry: {name}"
+        return True, self.last_info
+
+    def delete_entry(self, name: str) -> tuple[bool, str]:
+        """Remove an entry by ``name``. No-op if absent."""
+        target = name.strip()
+        if not target:
+            return False, "name is required"
+        with self._lock:
+            new_entries = [e for e in self.entries if str(e.get("name") or "") != target]
+            if len(new_entries) == len(self.entries):
+                return False, f"no entry named {target!r}"
+            raw = _serialise_catalog(new_entries)
+            try:
+                self._persist_bytes(raw)
+            except OSError as e:
+                return False, str(e)
+            self.entries = new_entries
+            self.last_error = ""
+            self.last_info = f"deleted entry: {target}"
+        return True, self.last_info
+
+    def _persist_bytes(self, raw: bytes) -> None:
+        """Atomic-replace ``self.persist_path`` with ``raw`` via
+        tempfile + rename so a crash mid-write can never leave a
+        half-written catalog.toml. Callers hold ``self._lock``."""
+        tmp = self.persist_path + ".tmp"
+        with open(tmp, "wb") as f:
+            f.write(raw)
+        os.replace(tmp, self.persist_path)
+
 
 class Auth:
     COOKIE = "withcache-token"
@@ -878,10 +1023,24 @@ class Handler(http.server.BaseHTTPRequestHandler):
         "/admin/cancel",
         "/admin/clear",
         "/admin/catalog_refresh",
+        "/admin/catalog_set_url",
+        "/admin/catalog_upload",
+        "/admin/catalog_add_entry",
+        "/admin/catalog_delete_entry",
     )
 
     def do_POST(self):
         parsed = urllib.parse.urlsplit(self.path)
+        # /admin/catalog_upload reads its own body (multipart); everything
+        # else uses the form parser. Don't try to url-decode multipart
+        # bytes.
+        if parsed.path == "/admin/catalog_upload":
+            if not self.is_authed():
+                self.send_text(401, "login required\n")
+                return
+            self._handle_catalog_upload()
+            self.respond_admin()
+            return
         form = self.read_form()
         if parsed.path == "/ui/login":
             self.handle_login_submit(form)
@@ -907,6 +1066,29 @@ class Handler(http.server.BaseHTTPRequestHandler):
                 self.mgr.clear_finished()
             elif parsed.path == "/admin/catalog_refresh":
                 self.catalog.fetch_now()
+            elif parsed.path == "/admin/catalog_set_url":
+                ok, msg = self.catalog.set_url_override(form.get("url", ""))
+                if ok:
+                    # Trigger an immediate fetch so the operator sees
+                    # the new source's entries without a second click.
+                    self.catalog.fetch_now()
+                else:
+                    self.catalog.last_error = msg
+            elif parsed.path == "/admin/catalog_add_entry":
+                entry = {
+                    "name": form.get("name", ""),
+                    "src": form.get("src", ""),
+                    "format": form.get("format", ""),
+                    "arch": form.get("arch", ""),
+                    "sha256": form.get("sha256", ""),
+                }
+                ok, msg = self.catalog.add_entry(entry)
+                if not ok:
+                    self.catalog.last_error = msg
+            elif parsed.path == "/admin/catalog_delete_entry":
+                ok, msg = self.catalog.delete_entry(form.get("name", ""))
+                if not ok:
+                    self.catalog.last_error = msg
             self.respond_admin()
         else:
             self.send_text(404, "not found\n")
@@ -1089,6 +1271,55 @@ class Handler(http.server.BaseHTTPRequestHandler):
         body = self.rfile.read(length).decode("utf-8") if length else ""
         return {k: v[0] for k, v in urllib.parse.parse_qs(body).items()}
 
+    def _handle_catalog_upload(self) -> None:
+        """Parse a multipart/form-data body with a single ``catalog``
+        file part and forward the raw bytes to
+        ``CatalogState.replace_from_bytes``. Stdlib-only: uses
+        ``email.parser.BytesParser`` to walk the parts (avoids the
+        ``cgi`` module which is slated for removal). On success or
+        failure the outcome is recorded in ``last_info`` /
+        ``last_error`` so ``respond_admin`` renders it inline."""
+        content_type = self.headers.get("Content-Type", "") or ""
+        if not content_type.startswith("multipart/"):
+            self.catalog.last_error = "expected multipart/form-data"
+            return
+        length = int(self.headers.get("Content-Length", 0) or 0)
+        if length <= 0:
+            self.catalog.last_error = "empty upload"
+            return
+        body = self.rfile.read(length)
+        # BytesParser needs a full "MIME message" header line so it
+        # knows the Content-Type; prepend it verbatim from the request.
+        prelude = f"MIME-Version: 1.0\r\nContent-Type: {content_type}\r\n\r\n".encode()
+        try:
+            import email.parser
+            import email.policy
+
+            msg = email.parser.BytesParser(policy=email.policy.default).parsebytes(prelude + body)
+        except Exception as e:  # noqa: BLE001 -- any parse error is a bad upload
+            self.catalog.last_error = f"multipart parse failed: {e}"
+            return
+        if not msg.is_multipart():
+            self.catalog.last_error = "no multipart parts found"
+            return
+        payload_bytes: bytes | None = None
+        filename = "upload"
+        for part in msg.iter_parts():
+            disp = part.get("Content-Disposition", "") or ""
+            if 'name="catalog"' not in disp:
+                continue
+            payload_bytes = part.get_payload(decode=True)
+            candidate_filename = part.get_filename()
+            if candidate_filename:
+                filename = candidate_filename
+            break
+        if not payload_bytes:
+            self.catalog.last_error = "upload missing 'catalog' file part"
+            return
+        ok, msg_text = self.catalog.replace_from_bytes(payload_bytes, source_label=filename)
+        if not ok:
+            self.catalog.last_error = msg_text
+
     def send_text(self, code: int, text: str):
         data = text.encode("utf-8")
         self.send_response(code)
@@ -1136,6 +1367,13 @@ class Handler(http.server.BaseHTTPRequestHandler):
     _PRIMARY_RGB = "143, 27, 113"
 
     def _head(self, title: str) -> str:
+        """Emit the shared page prelude: Bootstrap + icons + htmx +
+        the full bty-family chrome CSS. Every service (bty, withcache,
+        nbdmux) uses this same block; the only per-service knob is the
+        primary hue (``--bs-primary`` and the derived button /
+        rgba() variants). See bty's ``_layout.html`` for the origin
+        of these class names -- kept identical here so operators
+        moving between consoles see one visual grammar."""
         primary = self._PRIMARY_HEX
         hover = self._PRIMARY_HOVER
         rgb = self._PRIMARY_RGB
@@ -1147,9 +1385,11 @@ class Handler(http.server.BaseHTTPRequestHandler):
 <link rel="stylesheet" href="/static/bootstrap-icons.min.css">
 <script src="/static/htmx.min.js"></script>
 <style>
-  /* Bootstrap 5 exposes --bs-primary + a matching -rgb triplet
-     used for translucent variants (alerts, focus rings, .bg-*-
-     subtle). Overriding both here re-tints every stock component
+  /* Palette anchor for the three-service trio (bty navy,
+     withcache dark-magenta, nbdmux magenta). Bootstrap 5
+     exposes --bs-primary + a matching -rgb triplet used for
+     translucent variants (alerts, focus rings, .bg-*-subtle).
+     Overriding both here re-tints every stock component
      without patching bootstrap.min.css. */
   :root {{
     --bs-primary: {primary};
@@ -1157,51 +1397,254 @@ class Handler(http.server.BaseHTTPRequestHandler):
     --bs-link-color: {primary};
     --bs-link-hover-color: {hover};
   }}
-  .btn-primary {{ --bs-btn-bg: {primary}; --bs-btn-border-color: {primary};
-                 --bs-btn-hover-bg: {hover}; --bs-btn-hover-border-color: {hover};
-                 --bs-btn-active-bg: {hover}; --bs-btn-active-border-color: {hover}; }}
+  .btn-primary {{
+    --bs-btn-bg: {primary};
+    --bs-btn-border-color: {primary};
+    --bs-btn-hover-bg: {hover};
+    --bs-btn-hover-border-color: {hover};
+    --bs-btn-active-bg: {hover};
+    --bs-btn-active-border-color: {hover};
+  }}
   .bg-primary {{ --bs-bg-opacity: 1; background-color: {primary} !important; }}
   .text-primary {{ --bs-text-opacity: 1; color: {primary} !important; }}
   .border-primary {{ --bs-border-opacity: 1; border-color: {primary} !important; }}
-  /* Brand strip: navy -> dark-magenta -> magenta gradient shared
-     across bty (navy), withcache (dark-magenta) and nbdmux
-     (magenta) so the trio reads as one product family from any
-     of the three consoles. */
-  .brand-accent {{ height: 3px;
-    background: linear-gradient(90deg, #0d3585 0%, #8f1b71 50%, #d63384 100%); }}
+  /* Brand strip: a thin gradient accent above the navbar.
+     Stable across themes; defined inline rather than in
+     bootstrap.min.css so it renders even when the CSS load
+     races the initial paint. Shared navy -> dark-magenta ->
+     magenta gradient across bty (navy), withcache
+     (dark-magenta) and nbdmux (magenta) so the trio reads as
+     one product family from any of the three consoles. */
+  .brand-accent {{
+    height: 3px;
+    background: linear-gradient(90deg, #0d3585 0%, #8f1b71 50%, #d63384 100%);
+  }}
+  /* The accent + navbar + sub-nav pin to the top as one unit so
+     the sub-nav jump links stay visible while scrolling. */
+  .sticky-header {{
+    position: sticky;
+    top: 0;
+    z-index: 1030;
+  }}
+  /* In-page ``#anchor`` jumps (the sub-nav tab pills) land below
+     the sticky header instead of under it. */
+  html {{
+    scroll-padding-top: 6.5rem;
+    scroll-behavior: smooth;
+  }}
+  /* Brand pill keeps the same padding + radius everywhere; the
+     ``brand-active`` variant lights up on the home page so the
+     brand doubles as a Home indicator. */
+  .navbar-brand {{
+    border-radius: 0.5rem;
+    padding-left: 0.6rem;
+    padding-right: 0.6rem;
+    margin-right: 0.25rem;
+    transition: background-color 0.15s;
+  }}
+  .navbar-brand.brand-active {{
+    background-color: rgba({rgb}, 0.85);
+  }}
+  .navbar-brand:hover {{
+    background-color: rgba(255, 255, 255, 0.06);
+  }}
+  .navbar-brand.brand-active:hover {{
+    background-color: rgba({rgb}, 0.95);
+  }}
+  /* Version sits in the navbar alongside the brand pill but
+     OUTSIDE it -- so the brand button stays a clean click target
+     and the version reads as adjacent metadata. */
+  .navbar-version {{
+    color: rgba(255, 255, 255, 0.55);
+    font-weight: 400;
+    font-size: 0.85rem;
+    align-self: center;
+    white-space: nowrap;
+  }}
+  .navbar-brand .brand-icon {{
+    /* Sized to match bty's mascot PNG (1.05rem tall). Using a
+       Bootstrap Icon rather than an image keeps the shell
+       stdlib-only. */
+    font-size: 1.05rem;
+    vertical-align: -0.05rem;
+  }}
+  .navbar .nav-btn {{
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.4rem 0.8rem;
+    margin-right: 0.25rem;
+    border-radius: 0.5rem;
+    color: rgba(255, 255, 255, 0.85);
+    text-decoration: none;
+    transition: background-color 0.15s;
+  }}
+  .navbar .nav-btn:hover {{
+    background-color: rgba(255, 255, 255, 0.10);
+    color: #fff;
+  }}
+  .navbar .nav-btn.active {{
+    background-color: {primary};
+    color: #fff;
+    box-shadow: 0 0 0 1px rgba({rgb}, 0.6);
+  }}
+  .navbar .nav-btn i {{
+    font-size: 1.05rem;
+  }}
+  /* User-bar: a single pill containing username + logout, with a
+     thin vertical divider between them. Visually one widget,
+     but two click targets and zero JavaScript. */
+  .user-bar {{
+    display: inline-flex;
+    align-items: stretch;
+    border-radius: 999px;
+    background-color: rgba(255, 255, 255, 0.08);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    overflow: hidden;
+    font-size: 0.85rem;
+  }}
+  .user-bar-name {{
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.35rem 0.8rem;
+    color: rgba(255, 255, 255, 0.92);
+  }}
+  .user-bar-name code {{
+    color: #fff;
+    background: transparent;
+    padding: 0;
+  }}
+  .user-bar-divider {{
+    width: 1px;
+    background-color: rgba(255, 255, 255, 0.18);
+  }}
+  .user-bar-action {{
+    display: inline-flex;
+    align-items: center;
+    padding: 0.35rem 0.7rem;
+    background: transparent;
+    border: none;
+    color: rgba(255, 255, 255, 0.85);
+    text-decoration: none;
+    transition: background-color 0.15s, color 0.15s;
+  }}
+  .user-bar-action:hover,
+  .user-bar-action:focus {{
+    background-color: rgba(255, 255, 255, 0.10);
+    color: #fff;
+    outline: none;
+  }}
+  .user-bar-action.active {{
+    background-color: rgba(255, 255, 255, 0.16);
+    color: #fff;
+  }}
+  /* Logout hover keeps the danger-red signal so it doesn't
+     look indistinguishable from the account action. */
+  .user-bar-logout:hover,
+  .user-bar-logout:focus {{
+    background-color: rgba(220, 53, 69, 0.65);
+    color: #fff;
+  }}
+  /* Sub-nav strip. Sits immediately below the main ``bg-dark``
+     navbar; coloured CLEARLY lighter so it reads as "second-tier
+     nav, still chrome". Same ``#495057`` (--bs-gray-700) bty
+     uses so the boundary is unambiguous regardless of theme. */
+  .subnav-strip {{
+    background-color: #495057;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.10);
+    padding-top: 0.25rem;
+    padding-bottom: 0.25rem;
+    font-size: 0.85rem;
+    line-height: 1.4;
+  }}
+  .subnav-strip > .container {{
+    min-height: 2rem;
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+  }}
+  .subnav-strip .form-control-sm,
+  .subnav-strip .btn-sm,
+  .subnav-strip a,
+  .subnav-strip label,
+  .subnav-strip .small,
+  .subnav-strip small {{
+    font-size: inherit;
+    line-height: inherit;
+  }}
+  .subnav-strip .form-control-sm,
+  .subnav-strip .btn-sm {{
+    padding-top: 0.15rem;
+    padding-bottom: 0.15rem;
+  }}
+  .subnav-strip .nav-pills {{
+    gap: 0.25rem;
+  }}
+  .subnav-strip .nav-pills .nav-link {{
+    color: rgba(255, 255, 255, 0.78);
+    padding: 0.15rem 0.55rem;
+  }}
+  .subnav-strip .nav-pills .nav-link:hover {{
+    color: #fff;
+    background-color: rgba(255, 255, 255, 0.10);
+  }}
+  .subnav-strip .nav-pills .nav-link.active-tab {{
+    color: #fff;
+    background-color: {primary};
+  }}
+  .subnav-strip .text-muted {{
+    color: rgba(255, 255, 255, 0.55) !important;
+  }}
+  .subnav-strip code {{
+    color: rgba(255, 255, 255, 0.85);
+    background-color: transparent;
+  }}
+  .subnav-strip a {{
+    color: rgba(255, 255, 255, 0.78);
+  }}
+  .subnav-strip a:hover {{
+    color: #fff;
+  }}
+  /* Withcache-specific bits kept minimal. Everything else
+     inherits from Bootstrap + the chrome above. */
   code {{ color: inherit; font-size: .85em; }}
   .url {{ word-break: break-all; }}
   .num {{ text-align: right; }}
   .mono {{ font-family: var(--bs-font-monospace); font-size: .85em; }}
   #spin {{ width: 7rem; height: .5rem; margin: 0; }}
-  /* Tabs: Bootstrap nav-tabs, tinted via the active class. The
-     content panels toggle visibility via ``section.tab.active-tab``
-     so the same 1 Hz htmx innerHTML swap that used to work with
-     the Pico shell keeps working here without changing the JS. */
-  nav.tabs .nav-link {{ color: var(--bs-secondary-color); border: none;
-    border-bottom: 2px solid transparent; padding: .45rem .9rem;
-    font-size: .9rem; margin-bottom: -1px; }}
-  nav.tabs .nav-link:hover {{ color: var(--bs-body-color); }}
-  nav.tabs .nav-link.active-tab {{ color: var(--bs-body-color);
-    border-bottom-color: var(--bs-primary); font-weight: 600; }}
-  section.tab {{ display: none; padding-top: .75rem; }}
+  /* Tab content panels: shown only when the section carries
+     ``.active-tab``. Same hook the previous nav-tabs code used;
+     unchanged so the existing htmx post-swap script keeps
+     working. */
+  section.tab {{ display: none; padding-top: .25rem; }}
   section.tab.active-tab {{ display: block; }}
 </style>
 </head>"""
 
     def render_login(self, error: str = "") -> str:
+        """The unauthenticated shell: accent strip + dark navbar with the
+        brand pill (no user-bar since there's no session), then a
+        centered login card. Same chrome the authenticated page uses,
+        so the operator sees continuity across the auth boundary."""
         err = f'<div class="alert alert-danger">{html.escape(error)}</div>' if error else ""
         return f"""{self._head("withcache - login")}
-<body>
+<body class="bg-light">
+<div class="sticky-header">
 <div class="brand-accent"></div>
-<main class="container py-5">
-  <div class="card mx-auto" style="max-width: 24rem;">
+<nav class="navbar navbar-expand-md bg-dark navbar-dark py-2">
+    <div class="container">
+        <a class="navbar-brand fw-semibold brand-active" href="/">
+            <i class="bi bi-database brand-icon me-1"></i>WITHCACHE
+        </a>
+        <span class="navbar-version">v{html.escape(__version__)}</span>
+    </div>
+</nav>
+</div>
+<main class="container">
+  <div class="card mx-auto mt-5" style="max-width: 24rem;">
     <div class="card-body">
-      <h3 class="card-title fw-bold text-primary">
-        <i class="bi bi-hdd-stack"></i> withcache
-        <small class="text-muted fs-6">v{html.escape(__version__)}</small>
-      </h3>
-      <p class="text-muted small mb-3">Operator login</p>
+      <h5 class="card-title mb-3">Operator login</h5>
       {err}
       <form method="post" action="/ui/login">
         <div class="mb-3">
@@ -1215,56 +1658,91 @@ class Handler(http.server.BaseHTTPRequestHandler):
 </main></body></html>"""
 
     def render_page(self) -> str:
-        logout = (
-            '<form method="post" action="/ui/logout" class="d-inline m-0">'
-            '<button type="submit" class="btn btn-sm btn-outline-secondary">'
-            "Log out</button></form>"
+        """The authenticated shell: sticky-header wrapping the accent
+        strip, the dark navbar (brand pill + version + user-bar), and
+        the subnav strip carrying the tab pills. Then main.container
+        with the "Add from URI" card and the htmx-swapped #dash
+        region. Same chrome bty uses; only ``--bs-primary`` differs."""
+        user_bar = (
+            '<div class="user-bar mt-2 mt-md-0" title="Operator session">'
+            '<span class="user-bar-name">'
+            '<i class="bi bi-person-circle"></i><code>operator</code>'
+            "</span>"
+            '<span class="user-bar-divider"></span>'
+            '<form action="/ui/logout" method="post" class="m-0 d-inline-flex">'
+            '<button type="submit" class="user-bar-action user-bar-logout" title="Sign out">'
+            '<i class="bi bi-box-arrow-right"></i>'
+            "</button></form>"
+            "</div>"
             if self.auth.enabled
             else ""
         )
         return f"""{self._head("withcache cache-host")}
-<body>
+<body class="bg-light">
+<!-- Sticky header: the accent strip, the main navbar, and the
+     sub-nav strip travel together and pin to the top so the tab
+     pills stay reachable while scrolling a long list. -->
+<div class="sticky-header">
 <div class="brand-accent"></div>
-<nav class="navbar navbar-expand navbar-light bg-light border-bottom">
-  <div class="container">
-    <a class="navbar-brand fw-bold text-primary" href="/">
-      <i class="bi bi-hdd-stack"></i> withcache
-      <span class="badge bg-primary bg-opacity-10 text-primary ms-1"
-        >v{html.escape(__version__)}</span>
-    </a>
-    <div class="d-flex align-items-center gap-3">
-      <progress id="spin" class="htmx-indicator"></progress>
-      {logout}
+<nav class="navbar navbar-expand-md bg-dark navbar-dark py-2">
+    <div class="container">
+        <a class="navbar-brand fw-semibold brand-active" href="/">
+            <i class="bi bi-database brand-icon me-1"></i>WITHCACHE
+        </a>
+        <div class="d-flex flex-grow-1 align-items-center flex-wrap">
+            <div class="me-auto d-flex flex-wrap">
+                <!-- withcache is a single-page dashboard: no middle
+                     nav-btns. me-auto pushes version + user-bar right. -->
+            </div>
+            <span class="navbar-version me-2">v{html.escape(__version__)}</span>
+            {user_bar}
+        </div>
     </div>
-  </div>
 </nav>
-<main class="container py-4">
-  <div class="card mb-4">
-    <div class="card-header"><i class="bi bi-cloud-download text-primary"></i> Add from URI</div>
-    <div class="card-body">
+
+<!-- Sub-nav strip. Left side carries the five tab pills below the
+     main navbar; right side carries the page-level "Add from URI"
+     action (bty convention: page-level actions live in the subnav's
+     right-hand subnav-actions slot, not as a full-width card in
+     main). The tab pills are rendered STATIC here so labels don't
+     flicker on the 1 Hz htmx dashboard swap. Per-tab counts live
+     in the summary line inside the dash content and update on
+     every swap. -->
+<div class="subnav-strip">
+  <div class="container">
+    <ul class="nav nav-pills flex-nowrap flex-md-wrap m-0">
+      <li class="nav-item"><a class="nav-link" href="#tab-cached">Cached</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tab-streams">Streams</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tab-downloads">Downloads</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tab-misses">Misses</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tab-catalog">Catalog</a></li>
+    </ul>
+    <div class="subnav-actions ms-auto d-flex align-items-center gap-1">
       <form hx-post="/admin/fetch" hx-target="#dash" hx-swap="innerHTML"
-            hx-indicator="#spin" hx-on::after-request="this.reset()">
-        <div class="input-group">
-          <input class="form-control" type="url" name="url"
-            placeholder="https://origin/path/artifact.tar.gz" required>
-          <button class="btn btn-primary" type="submit" style="white-space: nowrap;"
-            >Fetch &amp; store</button>
-        </div>
+            hx-indicator="#spin" hx-on::after-request="this.reset()"
+            class="m-0 d-flex align-items-center gap-1">
+        <input class="form-control form-control-sm" type="url" name="url"
+               style="width: 22rem;"
+               placeholder="https://origin/path/artifact.tar.gz" required>
+        <button class="btn btn-sm btn-primary" type="submit" title="Add from URI"
+                >Fetch</button>
       </form>
+      <progress id="spin" class="htmx-indicator ms-1"
+                style="width:4rem;height:.4rem;"></progress>
     </div>
   </div>
+</div>
+</div><!-- /.sticky-header -->
+
+<main class="container py-4">
 
   <!-- The hx-trigger gates polling on the user NOT having an active
        text selection, so highlight-and-copy a URL out of a table cell
-       isn't wiped by the 1 Hz refresh. ``isCollapsed`` is true when
-       there's no selection or the caret is a zero-width point; once
-       the operator releases / clears the selection polling resumes
-       on the next 1 s tick.
-       ``hx-headers`` sends the current URL hash (the active tab id)
-       as ``X-Active-Tab`` on every refresh so the server can bake
-       ``.active-tab`` into the rendered HTML -- eliminating the
-       visible flicker the post-swap JS-applied class would otherwise
-       cause when the new innerHTML lands without the class. -->
+       isn't wiped by the 1 Hz refresh. hx-headers sends the current
+       URL hash (the active tab id) as X-Active-Tab on every refresh
+       so the server can bake .active-tab into the rendered HTML,
+       eliminating the visible flicker the post-swap JS-applied class
+       would otherwise cause when the new innerHTML lands. -->
   <div id="dash" hx-get="/admin/dash"
        hx-trigger="load, every 1s [document.getSelection().isCollapsed]"
        hx-swap="innerHTML"
@@ -1272,16 +1750,15 @@ class Handler(http.server.BaseHTTPRequestHandler):
     {self.render_dash(active_tab=(self.headers.get("X-Active-Tab") or "").strip())}
   </div>
 
-  <!-- Tab activation. Applies an ``active-tab`` class to the
-       ``section.tab`` whose id matches the URL hash (defaulting to
-       the first section when no hash is set) and to the
-       corresponding ``nav.tabs a``. Runs on initial load, on every
-       click into a tab link (so the operator gets immediate
-       feedback before the next htmx tick), and on every
-       ``htmx:afterSettle`` so the class survives the 1 Hz
-       innerHTML replacement of ``#dash``. Without this the
-       previous ``:target``-based CSS would snap the operator back
-       to the first tab within a second of any click. -->
+  <!-- Tab activation: apply .active-tab to the section (inside
+       #dash) AND to the matching subnav pill (outside #dash) whose
+       id/hash matches the current URL hash. Runs on hashchange, on
+       click into a tab link, and on every htmx:afterSettle so the
+       class survives the 1 Hz innerHTML replacement of #dash.
+       Subnav pills live outside #dash so the JS-applied class on
+       them is not touched by the swap; sections inside #dash also
+       get the class baked server-side (via X-Active-Tab) so there
+       is no visible flicker between swap and JS re-apply. -->
   <script>
     (function () {{
       function applyActiveTab() {{
@@ -1293,7 +1770,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
         sections.forEach(function (s) {{
           s.classList.toggle('active-tab', s.id === hash);
         }});
-        document.querySelectorAll('#dash nav.tabs a').forEach(function (a) {{
+        document.querySelectorAll('.subnav-strip .nav-pills .nav-link').forEach(function (a) {{
           var target = (a.getAttribute('href') || '').replace(/^#/, '');
           a.classList.toggle('active-tab', target === hash);
         }});
@@ -1301,7 +1778,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
       window.addEventListener('hashchange', applyActiveTab);
       document.body.addEventListener('htmx:afterSettle', applyActiveTab);
       document.addEventListener('click', function (ev) {{
-        var a = ev.target.closest && ev.target.closest('#dash nav.tabs a');
+        var a = ev.target.closest && ev.target.closest('.subnav-strip .nav-pills .nav-link');
         if (a) setTimeout(applyActiveTab, 0);
       }});
       applyActiveTab();
@@ -1317,7 +1794,7 @@ class Handler(http.server.BaseHTTPRequestHandler):
         # 1 Hz refresh (and on every operator click via the same
         # script that watches hashchange). Unknown / empty value
         # defaults to the first tab.
-        _TAB_IDS = ("tab-cached", "tab-streams", "tab-downloads", "tab-misses")
+        _TAB_IDS = ("tab-cached", "tab-streams", "tab-downloads", "tab-misses", "tab-catalog")
         if active_tab not in _TAB_IDS:
             active_tab = _TAB_IDS[0]
 
@@ -1442,24 +1919,22 @@ class Handler(http.server.BaseHTTPRequestHandler):
         njobs = len(jobs)
 
         catalog_rows = self._catalog_rows()
+        ncatalog = len(self.catalog.entries)
 
+        # The per-tab count summary lives here (inside the htmx-swapped
+        # region) so it updates every second. Tab labels themselves
+        # live in the static sub-nav strip in ``render_page`` per bty
+        # convention -- labels are chrome, counts are content.
         return f"""
-  <p class="text-muted small mb-2">{nblobs} cached ({used}){full}
-    &middot; {nmisses} pending miss(es)</p>
-  <nav class="tabs border-bottom mb-2">
-    <ul class="nav">
-      <li class="nav-item"><a class="nav-link {_active("tab-cached").lstrip()}"
-        href="#tab-cached">Cached ({nblobs})</a></li>
-      <li class="nav-item"><a class="nav-link {_active("tab-streams").lstrip()}"
-        href="#tab-streams">Streams ({nstreams})</a></li>
-      <li class="nav-item"><a class="nav-link {_active("tab-downloads").lstrip()}"
-        href="#tab-downloads">Downloads ({njobs})</a></li>
-      <li class="nav-item"><a class="nav-link {_active("tab-misses").lstrip()}"
-        href="#tab-misses">Misses ({nmisses})</a></li>
-      <li class="nav-item"><a class="nav-link {_active("tab-catalog").lstrip()}"
-        href="#tab-catalog">Catalog ({len(self.catalog.entries)})</a></li>
-    </ul>
-  </nav>
+  <p class="text-muted small mb-3">
+    <span class="badge bg-primary bg-opacity-10 text-primary me-1">{nblobs} cached ({used}){
+            full
+        }</span>
+    <span class="badge bg-secondary bg-opacity-10 text-secondary me-1">{nstreams} streams</span>
+    <span class="badge bg-secondary bg-opacity-10 text-secondary me-1">{njobs} downloads</span>
+    <span class="badge bg-secondary bg-opacity-10 text-secondary me-1">{nmisses} misses</span>
+    <span class="badge bg-secondary bg-opacity-10 text-secondary">{ncatalog} catalog</span>
+  </p>
 
   <section id="tab-cached" class="tab{_active("tab-cached")}">
     <div class="table-responsive"><table class="table table-sm table-striped table-hover mb-0">
@@ -1506,29 +1981,10 @@ class Handler(http.server.BaseHTTPRequestHandler):
   </section>
 
   <section id="tab-catalog" class="tab{_active("tab-catalog")}">
-    <div class="d-flex align-items-center justify-content-between mb-2 flex-wrap gap-2">
-      <div>
-        <div><small class="text-muted">source</small>
-          &nbsp;<code>{html.escape(self.catalog.url)}</code></div>
-        <div><small class="text-muted">fetched</small>
-          &nbsp;<code>{html.escape(self.catalog.fetched_at) or "never"}</code>
-          {
-            (
-                f'<span class="badge bg-danger-subtle text-danger ms-1">'
-                f"{html.escape(self.catalog.last_error)}</span>"
-            )
-            if self.catalog.last_error
-            else ""
-        }</div>
-      </div>
-      <form hx-post="/admin/catalog_refresh" hx-target="#dash" hx-swap="innerHTML"
-            hx-indicator="#spin" class="m-0">
-        <button class="btn btn-sm btn-primary" type="submit">Refresh</button>
-      </form>
-    </div>
+    {self._catalog_controls_html()}
     <div class="table-responsive"><table class="table table-sm table-striped table-hover mb-0">
       <thead class="table-light"><tr>
-        <th>Name</th><th>Format</th><th>Arch</th><th>Size</th><th>Source</th>
+        <th>Name</th><th>Format</th><th>Arch</th><th>Size</th><th>Source</th><th></th>
       </tr></thead>
       <tbody>{catalog_rows}</tbody>
     </table></div>
@@ -1536,15 +1992,20 @@ class Handler(http.server.BaseHTTPRequestHandler):
 
     def _catalog_rows(self) -> str:
         """One <tr> per catalog image. Cells: name, format, arch,
-        human-readable size, and a Source cell whose URL is the
-        withcache /b/ token (so a click through pulls via cache).
-        Empty catalog rows to a "not fetched yet" placeholder + a
-        hint about the Refresh button."""
+        human-readable size, a Source cell whose URL is the
+        withcache /b/ token (so a click through pulls via cache),
+        and a Delete button that removes the entry via
+        ``/admin/catalog_delete_entry``. Empty catalog rows to a
+        "not fetched yet" placeholder + a hint about the Refresh
+        or Fetch controls above."""
         entries = self.catalog.entries
         if not entries:
-            hint = self.catalog.last_error or "click Refresh above to fetch the catalog manifest"
+            hint = (
+                self.catalog.last_error
+                or "click Fetch / Refresh above, or upload a catalog.toml, to populate."
+            )
             return (
-                '<tr><td colspan="5" class="text-center text-muted">'
+                '<tr><td colspan="6" class="text-center text-muted">'
                 f"<em>{html.escape(hint)}</em></td></tr>"
             )
         rows: list[str] = []
@@ -1566,6 +2027,13 @@ class Handler(http.server.BaseHTTPRequestHandler):
                 src_cell = f'<a href="{link}" title="{html.escape(src)}">{html.escape(src)}</a>'
             else:
                 src_cell = html.escape(src)
+            delete_cell = (
+                '<form hx-post="/admin/catalog_delete_entry" hx-target="#dash" '
+                'hx-swap="innerHTML" hx-confirm="Delete this catalog entry?" class="m-0">'
+                f'<input type="hidden" name="name" value="{html.escape(name, quote=True)}">'
+                '<button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>'
+                "</form>"
+            )
             rows.append(
                 f"<tr>"
                 f"<td>{html.escape(name)}</td>"
@@ -1573,10 +2041,103 @@ class Handler(http.server.BaseHTTPRequestHandler):
                 f'<td class="mono"><small>{html.escape(arch)}</small></td>'
                 f"<td>{html.escape(size)}</td>"
                 f'<td class="url">{src_cell}</td>'
+                f"<td>{delete_cell}</td>"
                 "</tr>"
             )
         return "".join(rows)
 
+    def _catalog_controls_html(self) -> str:
+        """The top of the Catalog tab: source + fetched-at metadata,
+        the operator control forms (set URL / upload catalog.toml /
+        add single entry), and the outcome banner (last_info or
+        last_error). Split out so ``render_dash`` stays readable."""
+        catalog = self.catalog
+        env_pinned = bool(catalog.env_url)
+        # Outcome banner: preferred order is error (red) > info (green).
+        # Both are transient (overwritten on the next admin action).
+        banner = ""
+        if catalog.last_error:
+            banner = (
+                '<div class="alert alert-danger py-1 px-2 mb-2 small">'
+                f'<i class="bi bi-exclamation-triangle-fill me-1"></i>'
+                f"{html.escape(catalog.last_error)}</div>"
+            )
+        elif catalog.last_info:
+            banner = (
+                '<div class="alert alert-success py-1 px-2 mb-2 small">'
+                f'<i class="bi bi-check-circle-fill me-1"></i>'
+                f"{html.escape(catalog.last_info)}</div>"
+            )
+        url_input_attrs = (
+            'disabled title="pinned by env WITHCACHE_CATALOG_URL"' if env_pinned else ""
+        )
+        env_hint = (
+            '<span class="badge bg-secondary bg-opacity-10 text-secondary ms-1">env-pinned</span>'
+            if env_pinned
+            else ""
+        )
+        return f"""
+    <div class="row g-2 mb-2">
+      <div class="col-md-6">
+        <div class="d-flex flex-column">
+          <label class="form-label mb-1 small text-muted">Catalog URL {env_hint}</label>
+          <form hx-post="/admin/catalog_set_url" hx-target="#dash" hx-swap="innerHTML"
+                hx-indicator="#spin" class="m-0 d-flex align-items-center gap-1">
+            <input class="form-control form-control-sm" type="url" name="url"
+                   value="{html.escape(catalog.url, quote=True)}" required {url_input_attrs}>
+            <button class="btn btn-sm btn-primary" type="submit"
+                    {url_input_attrs}>Set &amp; fetch</button>
+            <button class="btn btn-sm btn-outline-secondary" type="button"
+                    hx-post="/admin/catalog_refresh" hx-target="#dash" hx-swap="innerHTML"
+                    hx-indicator="#spin" title="Refetch from current URL">Refresh</button>
+          </form>
+        </div>
+      </div>
+      <div class="col-md-6">
+        <label class="form-label mb-1 small text-muted">Upload catalog.toml</label>
+        <form hx-post="/admin/catalog_upload" hx-target="#dash" hx-swap="innerHTML"
+              hx-encoding="multipart/form-data" hx-indicator="#spin"
+              class="m-0 d-flex align-items-center gap-1">
+          <input class="form-control form-control-sm" type="file" name="catalog"
+                 accept=".toml,text/plain" required>
+          <button class="btn btn-sm btn-primary" type="submit">Upload</button>
+        </form>
+      </div>
+    </div>
+    <div class="d-flex flex-wrap align-items-end gap-2 mb-2">
+      <div>
+        <label class="form-label mb-0 small text-muted">Last fetched</label>
+        <div><code>{html.escape(catalog.fetched_at) or "never"}</code>
+             &middot; {len(catalog.entries)} entries</div>
+      </div>
+      <form hx-post="/admin/catalog_add_entry" hx-target="#dash" hx-swap="innerHTML"
+            hx-indicator="#spin" hx-on::after-request="this.reset()"
+            class="m-0 ms-auto d-flex align-items-end flex-wrap gap-1">
+        <div>
+          <label class="form-label mb-0 small text-muted">name</label>
+          <input class="form-control form-control-sm" name="name"
+                 style="width: 10rem;" placeholder="debian-13" required>
+        </div>
+        <div>
+          <label class="form-label mb-0 small text-muted">src</label>
+          <input class="form-control form-control-sm" name="src"
+                 style="width: 16rem;" placeholder="https://.../image.img.zst" required>
+        </div>
+        <div>
+          <label class="form-label mb-0 small text-muted">format</label>
+          <input class="form-control form-control-sm" name="format"
+                 style="width: 7rem;" placeholder="img.zst">
+        </div>
+        <div>
+          <label class="form-label mb-0 small text-muted">arch</label>
+          <input class="form-control form-control-sm" name="arch"
+                 style="width: 6rem;" placeholder="x86_64">
+        </div>
+        <button class="btn btn-sm btn-primary" type="submit">Add entry</button>
+      </form>
+    </div>
+    {banner}"""
+
     def _stream_progress_cell(self, s: Stream) -> str:
         """One progress cell for an active stream: a <progress> bar when the
         total is known (always for a cached blob, since the size came off
@@ -1669,13 +2230,18 @@ def main():
     httpd.mgr = mgr  # type: ignore[attr-defined]
     httpd.auto_fetch = not args.curate  # type: ignore[attr-defined]
     httpd.streams = StreamRegistry()  # type: ignore[attr-defined]
-    # Catalog state: env override, else the shipping default (nosi's
-    # rolling catalog manifest). Seeded from the last persisted
-    # catalog.toml on disk so a restart doesn't wipe the cache.
-    catalog_url = (os.environ.get("WITHCACHE_CATALOG_URL") or DEFAULT_CATALOG_URL).strip()
+    # Catalog state: env pin wins over everything, then the operator
+    # override on disk (set via /admin/catalog_set_url), then the
+    # shipping default (nosi's rolling catalog manifest). Seeded from
+    # the last persisted catalog.toml on disk so a restart doesn't
+    # wipe the cache.
+    env_catalog_url = (os.environ.get("WITHCACHE_CATALOG_URL") or "").strip()
+    catalog_url = env_catalog_url or DEFAULT_CATALOG_URL
     catalog = CatalogState(
         url=catalog_url,
         persist_path=os.path.join(store.data_dir, "catalog.toml"),
+        env_url=env_catalog_url,
+        url_override_path=os.path.join(store.data_dir, "catalog_url"),
     )
     catalog.load_persisted()
     httpd.catalog = catalog  # type: ignore[attr-defined]