imperal-sdk 4.2.2__tar.gz → 4.2.4__tar.gz

{imperal_sdk-4.2.2 → imperal_sdk-4.2.4}/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 4.2.4 — 2026-05-13
+
+**EXT-SECRETS-V1 — unconditional synthetic Secrets panel**
+
+In v4.2.3 the synthetic Secrets panel was registered conditionally on the
+first `@ext.secret(...)` call, which meant extensions that did not declare
+secrets had no menu entry — leaving end-users without a discoverable place
+to manage credentials when developers later add declarations.
+
+This release flips the registration to **unconditional**: every Extension
+instance auto-registers the synthetic `secrets` panel in `__init__` (slot
+`right`, title `Secrets`, icon `KeyRound`). When the manifest has zero
+declared secrets, the panel renders an empty state with developer guidance
+(`@ext.secret(...)` code example + link to docs). When declarations exist,
+it renders one card per secret with `is_set` status + Manage button.
+
+### Migration notes
+
+- **No code changes required**. Bump your ext's SDK pin to `>= 4.2.4` and
+  redeploy via Dev Portal — the Secrets tab appears automatically.
+- Extensions that genuinely never need credentials still get the tab; this
+  is intentional for UX consistency. Federal V32 contract still requires
+  `@ext.secret` for any real credential access at runtime.
+
+## 4.2.3 — 2026-05-13
+
+**EXT-SECRETS-V1 UX polish — synthetic `secrets` panel auto-injected**
+
+When an extension declares one or more `@ext.secret(...)` entries, the SDK
+now auto-registers a synthetic `secrets` panel (slot=`right`, title=`Secrets`,
+icon=`KeyRound`) so the user-facing Secrets manager appears alongside the
+extension's own tabs without the author writing any panel code.
+
+### Added
+
+- **Auto-injected `secrets` panel**: `Extension.secret(...)` on first call
+  registers a built-in handler from `imperal_sdk.secrets.panel_handler`. The
+  handler reads declared secrets + live is_set state from `ctx.secrets.list()`
+  and renders `ui.Card` rows with status badges + a `Manage` button that
+  routes to the dedicated `/ext/{ext_id}/secrets` page.
+- The synthetic panel uses **slot=`right`** defensively — most extensions use
+  `left` (sidebar nav) and `center` (main content); `right` is rarely-used so
+  the panel-sync logic in `imperal-ext-developer` won't overwrite it. If your
+  extension already declares a `right`-slot panel, your panel wins; users
+  still reach the Secrets UI via the chat-top ribbon and the direct
+  `/ext/{ext_id}/secrets` route.
+- Panel idempotent — multiple `@ext.secret(...)` calls register the panel
+  only once.
+
+### Migration notes
+
+- **No code changes required** to receive the synthetic panel. Bump your
+  ext's SDK pin to `>= 4.2.3` and redeploy via Dev Portal.
+- Once your extension is on v4.2.3+, the chat-top ribbon (added in Panel for
+  v4.2.2 discoverability) becomes redundant for that ext — synthetic panel
+  appears in the `right` slot as a proper tab.
+
 ## 4.2.2 — 2026-05-13
 
 ### Added — EXT-SECRETS-V1 (closes ARCH-D1 in compliance-posture.md)

{imperal_sdk-4.2.2 → imperal_sdk-4.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imperal-sdk
-Version: 4.2.2
+Version: 4.2.4
 Summary: SDK for building Imperal Cloud extensions
 Author: Valentin Scerbacov, Imperal, Inc.
 License-Expression: AGPL-3.0-or-later

{imperal_sdk-4.2.2 → imperal_sdk-4.2.4}/src/imperal_sdk/__init__.py

@@ -39,7 +39,7 @@ from imperal_sdk.secrets import (
     SecretValueTooLarge, SecretDeclarationConflict,
 )
 
-__version__ = "4.2.2"
+__version__ = "4.2.4"
 
 __all__ = [
     # Core

{imperal_sdk-4.2.2 → imperal_sdk-4.2.4}/src/imperal_sdk/extension.py

@@ -142,6 +142,36 @@ class Extension:
         # EXT-SECRETS-V1 (v4.2.2) — declared secrets emitted into manifest.secrets[]
         self._secrets: dict[str, "SecretSpec"] = {}
 
+        # EXT-SECRETS-V1 (v4.2.4) — auto-register synthetic 'secrets' panel
+        # unconditionally for every Extension. Empty state (no @ext.secret
+        # declared) renders developer guidance with code example. Federal
+        # contract enforced platform-side regardless of UI presence.
+        self._auto_register_secrets_panel()
+
+    def _auto_register_secrets_panel(self) -> None:
+        """Register the platform-provided 'secrets' panel.
+
+        Idempotent — only registers once per Extension instance. Slot
+        defaults to 'right' (least-used by typical extensions, lowest
+        collision risk with deploy-sync logic that keeps one panel per slot).
+        """
+        if "secrets" in self._panels:
+            return
+        try:
+            from imperal_sdk.secrets.panel_handler import (
+                builtin_secrets_panel_handler,
+            )
+        except Exception:
+            # If secrets package import fails, don't break Extension init.
+            return
+        self.panel(
+            "secrets",
+            slot="right",
+            title="Secrets",
+            icon="KeyRound",
+            refresh="manual",
+        )(builtin_secrets_panel_handler)
+
     def secret(
         self,
         name: str,
@@ -195,6 +225,11 @@ class Extension:
             )
         self._secrets[name] = spec
 
+        # EXT-SECRETS-V1 (v4.2.4): synthetic Secrets panel is now registered
+        # unconditionally in Extension.__init__ via _auto_register_secrets_panel.
+        # This call site is a no-op safety net for older bytecode paths.
+        self._auto_register_secrets_panel()
+
         def _decorator(target):
             return target  # syntactic anchor only — decorator is a no-op wrapper
 

imperal_sdk-4.2.4/src/imperal_sdk/secrets/panel_handler.py

@@ -0,0 +1,133 @@
+"""Built-in handler for the synthetic ``secrets`` panel.
+
+When an Extension declares one or more ``@ext.secret(...)`` entries, the SDK
+auto-registers a panel with ``panel_id='secrets'`` so the user-facing
+Secrets manager appears among the extension's other tabs (Overview /
+Analytics / Transactions / ...). The extension author doesn't write any
+panel code — the SDK provides this canonical handler.
+
+Federal contract: the handler renders a summary of declared secrets +
+links to the full /ext/{ext_id}/secrets page where Panel UI handles
+PUT/DELETE through type=password input + cleared-on-submit state. We
+do NOT inline the input form here because the canonical UI lives in
+Panel React (SecretManagerCard) — duplicating it in declarative ui.*
+primitives would split the federal contract (I-SECRETS-NEVER-LOGGED,
+no-echo, no-clipboard) across two implementations.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+async def builtin_secrets_panel_handler(ctx: Any, **_params: Any) -> dict:
+    """Render the synthetic secrets panel.
+
+    Returns a UINode dict (post-``.to_dict()``) that the kernel relays to
+    Imperal Panel. The panel shows one card per declared secret with
+    is_set status badge and a primary action that navigates to
+    /ext/{ext_id}/secrets — the full SecretManagerCard route.
+    """
+    # Import inside the handler to keep SDK init light and avoid
+    # circular imports if ui.* itself imports anything from secrets.
+    from imperal_sdk import ui
+
+    ext_id = getattr(ctx, "ext_id", "") or getattr(ctx, "extension_id", "") or ""
+
+    # Pull declared secrets from ctx if the kernel populated them; fall
+    # back to an empty list so the panel still renders cleanly.
+    declared = list(getattr(ctx, "_declared_secrets", {}).values()) if getattr(
+        ctx, "_declared_secrets", None
+    ) else []
+
+    # Try to fetch live is_set state per declared name (cheap meta read).
+    statuses: dict[str, dict] = {}
+    if hasattr(ctx, "secrets") and ctx.secrets is not None:
+        try:
+            live = await ctx.secrets.list()
+            for s in live:
+                # SecretStatus or dict — handle both.
+                name = getattr(s, "name", None) or (s.get("name") if isinstance(s, dict) else None)
+                if name is None:
+                    continue
+                statuses[name] = {
+                    "is_set": bool(getattr(s, "is_set", None) if not isinstance(s, dict) else s.get("is_set", False)),
+                    "last_accessed_at": (
+                        getattr(s, "last_accessed_at", None)
+                        if not isinstance(s, dict)
+                        else s.get("last_accessed_at")
+                    ),
+                }
+        except Exception:
+            statuses = {}
+
+    cards = []
+    for spec in declared:
+        name = getattr(spec, "name", None) or (spec.get("name") if isinstance(spec, dict) else None)
+        if not name:
+            continue
+        desc = getattr(spec, "description", "") or (spec.get("description", "") if isinstance(spec, dict) else "")
+        write_mode = (
+            getattr(spec, "write_mode", "user")
+            if not isinstance(spec, dict)
+            else spec.get("write_mode", "user")
+        )
+        status = statuses.get(name, {"is_set": False, "last_accessed_at": None})
+        is_set = bool(status.get("is_set"))
+        last_read = status.get("last_accessed_at")
+
+        # One card per secret with status + Manage button.
+        rows = [ui.Text(desc) if desc else None]
+        if is_set:
+            rows.append(ui.Badge("Set", color="green"))
+            if last_read:
+                rows.append(ui.Text(f"Last read: {last_read}", color="muted"))
+        else:
+            rows.append(ui.Badge("Not set", color="gray"))
+        if write_mode == "extension":
+            rows.append(ui.Text("(extension-write only — written after authorize)", color="muted"))
+
+        rows.append(ui.Button(
+            label="Manage" if is_set else "Set value",
+            variant="primary" if not is_set else "secondary",
+            on_click=ui.Navigate(path=f"/ext/{ext_id}/secrets#{name}"),
+        ))
+
+        cards.append(ui.Card(
+            title=name,
+            content=ui.Stack(children=[r for r in rows if r is not None]),
+        ))
+
+    if not cards:
+        cards.append(ui.Card(
+            title="No secrets declared",
+            content=ui.Stack(children=[
+                ui.Text(
+                    "This extension does not declare any secrets. If you are "
+                    "the developer, add an @ext.secret(...) declaration to "
+                    "your app.py and redeploy."
+                ),
+                ui.Link(
+                    text="Read @ext.secret reference →",
+                    href="https://docs.imperal.io/en/sdk/decorator-secret-reference/",
+                ),
+            ]),
+        ))
+
+    root = ui.Stack(children=[
+        ui.Heading(f"Secrets · {ext_id}", level=2),
+        ui.Text(
+            "Credentials this extension needs — API keys, OAuth tokens. "
+            "Stored encrypted in Vault; never visible to admins or in logs."
+        ),
+        *cards,
+        ui.Link(
+            text=f"Open full Secrets manager →",
+            href=f"/ext/{ext_id}/secrets",
+        ),
+    ])
+
+    # Match the wrapper contract from @ext.panel decorator — return .to_dict()
+    # of the root. The kernel wraps {"ui": ..., "panel_id": "secrets"}.
+    if hasattr(root, "to_dict"):
+        return root.to_dict()
+    return root