imperal-sdk 4.1.8__tar.gz → 4.2.0__tar.gz

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 4.2.0 — 2026-05-11
+
+### Added
+
+- **`Extension(system: bool = False)` kwarg** declares an extension as
+  a platform-managed system app. System apps are auto-installed for
+  every user on registration, never shown in marketplace listings, and
+  cannot be uninstalled. Federal contract additions:
+  - `I-SYSTEM-APPS-NEVER-UNINSTALLABLE` — uninstall on `system=true`
+    returns 403 at the auth-gw level.
+  - `I-MARKETPLACE-HIDES-SYSTEM` — `/v1/marketplace/*` SELECT queries
+    filter `system = FALSE` at the SQL layer.
+  - `I-SYSTEM-FLAG-RESERVED-FOR-IMPERAL` — only first-party Imperal
+    authors may set `system=True`; Dev Portal rejects 3rd-party
+    publishes at the author allowlist.
+- **Manifest field**: top-level `system: bool` is emitted by
+  `imperal build` whenever `Extension(system=…)` is set. `manifest.py`
+  and `manifest_schema.Manifest` both carry it; the JSON schema file
+  (`src/imperal_sdk/schemas/imperal.schema.json`) is regenerated.
+- **Validator V31**: local check that rejects `system=True` for
+  non-Imperal authors. Triggered by `IMPERAL_AUTHOR_ID` env var so
+  local dev without the env continues to pass (Dev Portal is the
+  authoritative gate at publish time). 4 new unit tests pinning the
+  contract.
+
+### Migration notes
+
+- The four first-party Imperal extensions (`admin`, `billing`,
+  `developer`, `automations`) should add `system=True` to their
+  `Extension(...)` declaration. Existing rows in `developer_apps.system`
+  were backfilled during the Sprint B platform deploy, so the live
+  marketplace already hides them — re-publishing them through the
+  Dev Portal will keep manifest and DB consistent.
+
+978 tests pass, 3 skipped.
+
+## 4.1.9 — 2026-05-10
+
+### Fixed
+
+- **`imperal init <name>` template now passes federal validators
+  cleanly.** The previous scaffold generated `Extension(name, version="1.0.0")`
+  without `display_name=`/`description=`/`icon=`/`actions_explicit=` —
+  failing V14 (description ≥40 chars), V15 (display_name ≥3 chars
+  ≠ app_id), V16 (per-function description ≥20 chars), and V21 (icon.svg
+  required) on the very first `imperal validate`. New scaffold writes
+  v4-correct kwargs, a proper `ChatExtension(...)` declaration, an
+  `icon.svg` placeholder (V21-compliant XML root + viewBox),
+  `requirements.txt: imperal-sdk>=4.0.0` (was `>=1.0.0`), and a test
+  file that exercises Pydantic param validation + `MockContext`.
+
+### Changed
+
+- CLI `init` next-steps message updated to the canonical workflow:
+  `pip install` → `imperal build` → `imperal validate` →
+  `imperal test` → `imperal deploy`.
+
+974 tests pass, 3 skipped.
+
 ## 4.1.8 — 2026-05-10
 
 ### Added

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/PKG-INFO

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

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/src/imperal_sdk/__init__.py

@@ -33,7 +33,7 @@ from imperal_sdk.validator_v1_6_0 import (
     validate_manifest_v1_6_0,
 )
 
-__version__ = "4.1.8"
+__version__ = "4.2.0"
 
 __all__ = [
     # Core

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/src/imperal_sdk/cli/main.py

@@ -67,75 +67,156 @@ def cli():
 @click.argument("name")
 @click.option("--template", type=click.Choice(["chat", "tool"]), default="chat", help="Extension template")
 def init(name: str, template: str):
-    """Scaffold a new extension project."""
+    """Scaffold a new extension project (federal v4 contract)."""
     os.makedirs(name, exist_ok=True)
     os.makedirs(f"{name}/tests", exist_ok=True)
 
+    title = name.replace("-", " ").replace("_", " ").title()
+    # V14 requires description ≥40 chars, V15 requires display_name ≥3 chars
+    # ≠ app_id, V16 requires per-function description ≥20 chars. We seed
+    # values that satisfy all three so `imperal build && imperal validate`
+    # passes immediately — no surprises for new authors.
+    display_name = f"{title} Extension"
+    description = (
+        f"{title} — a starter extension scaffolded by `imperal init`. "
+        f"Replace this description with something specific to your tool."
+    )
+
     if template == "chat":
-        main_content = f'''"""{name} — Imperal Cloud Extension."""
-from pydantic import BaseModel
+        main_content = f'''"""{title} extension — Imperal Cloud."""
+from pydantic import BaseModel, Field
 from imperal_sdk import Extension, ChatExtension, ActionResult
 
-ext = Extension("{name}", version="1.0.0")
-chat = ChatExtension(ext, tool_name="{name}", description="{name.replace('-', ' ').title()} extension")
+
+# Federal v4 Extension surface — V14 (description ≥40 chars), V15
+# (display_name ≥3 chars, ≠ app_id), V19 (actions_explicit=True), and
+# V21 (icon.svg required, XML <svg> root + viewBox) are all satisfied
+# by these defaults. Edit display_name + description before publish.
+ext = Extension(
+    "{name}",
+    version="1.0.0",
+    display_name={display_name!r},
+    description={description!r},
+    icon="icon.svg",
+    actions_explicit=True,
+    capabilities=[{name!r} + ":read"],
+)
+
+chat = ChatExtension(
+    ext,
+    tool_name={name.replace('-', '_')!r},
+    description={f"{title} — chat tool entrypoint."!r},
+)
 
 
 class GreetParams(BaseModel):
-    name: str = "World"
+    """Pydantic params model — V17 federal: typed BaseModel param required."""
+    name: str = Field(default="World", description="Person to greet")
 
 
-@chat.function("greet", description="Say hello", params={{}}, action_type="read")
+@chat.function(
+    "greet",
+    action_type="read",
+    description="Greet someone by name with a friendly message.",
+)
 async def fn_greet(ctx, params: GreetParams) -> ActionResult:
-    """Greet someone by name."""
+    """Echo a greeting to verify the extension loads + validators pass."""
     return ActionResult.success(
         data={{"message": f"Hello, {{params.name}}!"}},
         summary=f"Greeted {{params.name}}",
     )
 '''
     else:
-        main_content = f'''"""{name} — Imperal Cloud Extension."""
+        main_content = f'''"""{title} extension — Imperal Cloud (tool template, no chat surface)."""
 from imperal_sdk import Extension
 
-ext = Extension("{name}", version="1.0.0")
 
+ext = Extension(
+    "{name}",
+    version="1.0.0",
+    display_name={display_name!r},
+    description={description!r},
+    icon="icon.svg",
+    actions_explicit=True,
+    capabilities=[{name!r} + ":read"],
+)
 
-@ext.tool("{name}", description="{name.replace('-', ' ').title()}")
-async def hello(ctx, name: str = "World"):
-    """Say hello."""
-    return {{"message": f"Hello, {{name}}!"}}
+
+@ext.tool({name!r}, scopes=[{name!r} + ":read"], description={f"{title} — invoke from automations or chains."!r})
+async def fn_default(ctx, **kwargs):
+    """Stub tool. Replace with your own."""
+    return {{"message": "ok"}}
 '''
 
     with open(f"{name}/main.py", "w") as f:
         f.write(main_content)
 
+    # V21 federal: extensions MUST ship a valid SVG icon. We seed a tiny
+    # placeholder that passes the validator (XML root + viewBox + ≤100 KB).
+    with open(f"{name}/icon.svg", "w") as f:
+        f.write(
+            '<?xml version="1.0" encoding="UTF-8"?>\n'
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" '
+            'fill="none" stroke="currentColor" stroke-width="2" '
+            'stroke-linecap="round" stroke-linejoin="round" width="24" height="24">'
+            '<rect x="3" y="3" width="18" height="18" rx="2"/>'
+            '<path d="M9 9h6v6H9z"/>'
+            '</svg>\n'
+        )
+
     with open(f"{name}/requirements.txt", "w") as f:
-        f.write("imperal-sdk>=1.0.0\n")
+        f.write("imperal-sdk>=4.0.0\n")
 
     with open(f"{name}/tests/__init__.py", "w") as f:
         pass
 
-    test_content = f'''"""Tests for {name} extension."""
-import pytest
-from imperal_sdk.testing import MockContext
-from main import ext
-
-
-def test_extension_registered():
-    assert ext.app_id == "{name}"
-    assert ext.version == "1.0.0"
-'''
+    test_content = (
+        f'"""Tests for {name} extension."""\n'
+        f'import pytest\n'
+        f'from imperal_sdk.testing import MockContext\n'
+        f'from main import ext\n'
+    )
+    if template == "chat":
+        test_content += (
+            f'from main import GreetParams, fn_greet\n\n\n'
+            f'def test_extension_registered():\n'
+            f'    assert ext.app_id == "{name}"\n'
+            f'    assert ext.version == "1.0.0"\n'
+            f'    assert ext.display_name and ext.display_name != ext.app_id\n'
+            f'    assert len(ext.description) >= 40\n\n\n'
+            f'@pytest.mark.asyncio\n'
+            f'async def test_greet_returns_action_result():\n'
+            f'    ctx = MockContext(user_id="imp_u_test")\n'
+            f'    result = await fn_greet(ctx, GreetParams(name="Alex"))\n'
+            f'    assert result.status == "success"\n'
+            f'    assert "Alex" in result.summary\n'
+        )
+    else:
+        test_content += (
+            f'\n\ndef test_extension_registered():\n'
+            f'    assert ext.app_id == "{name}"\n'
+            f'    assert ext.version == "1.0.0"\n'
+            f'    assert "{name}" in ext.tools\n'
+        )
 
     with open(f"{name}/tests/test_main.py", "w") as f:
         f.write(test_content)
 
     with open(f"{name}/.gitignore", "w") as f:
-        f.write("venv/\n__pycache__/\n*.pyc\n.env\n.imperal/\n")
+        f.write(
+            "venv/\n.venv/\n__pycache__/\n*.pyc\n*.pyo\n.pytest_cache/\n"
+            ".env\n.imperal/\nimperal.json\n.DS_Store\n"
+        )
 
-    click.echo(f"Extension '{name}' created! (template: {template})")
+    click.echo(f"Extension '{name}' scaffolded (template: {template})")
+    click.echo(f"")
+    click.echo(f"Next steps:")
     click.echo(f"  cd {name}")
-    click.echo(f"  pip install imperal-sdk")
-    click.echo(f"  imperal validate")
-    click.echo(f"  imperal dev")
+    click.echo(f"  pip install 'imperal-sdk>=4.0.0'")
+    click.echo(f"  imperal build       # generates imperal.json")
+    click.echo(f"  imperal validate    # runs V14-V22+V24 federal validators")
+    click.echo(f"  imperal test        # smoke-test handlers via MockContext")
+    click.echo(f"  imperal deploy      # upload to panel.imperal.io/developer")
 
 
 @cli.command()

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/src/imperal_sdk/extension.py

@@ -115,6 +115,7 @@ class Extension:
         description: str = "",
         icon: str = "",
         actions_explicit: bool = True,
+        system: bool = False,
     ):
         self.app_id = app_id
         self.version = version
@@ -122,6 +123,7 @@ class Extension:
         self.description = description
         self.icon = icon
         self.actions_explicit = actions_explicit
+        self.system = system
         self.capabilities = capabilities or []
         self.migrations_dir = migrations_dir
         self._tools: dict[str, ToolDef] = {}

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/src/imperal_sdk/manifest.py

@@ -126,6 +126,7 @@ def generate_manifest(ext: Extension) -> dict:
         "description": ext.description or "",
         "icon": ext.icon or "",
         "actions_explicit": ext.actions_explicit,
+        "system": bool(getattr(ext, "system", False)),
         "capabilities": ext.capabilities,
         "tools": tools,
         "signals": signals,

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/src/imperal_sdk/manifest_schema.py

@@ -284,6 +284,12 @@ class Manifest(BaseModel):
     icon_size_bytes: Optional[int] = None
     lifecycle_hooks: Optional[Dict[str, Dict[str, Any]]] = None
 
+    # Federal v4.2.0 — `system=True` marks platform-managed extensions
+    # (admin / billing / developer / automations). Auto-installed for every
+    # user on registration, hidden from marketplace, cannot be uninstalled.
+    # Reserved for first-party Imperal authors (validator V31).
+    system: Optional[bool] = None
+
     # --- Marketplace merge (docs/imperal-cloud/developer-portal.md) ---
     name: Optional[str] = None
     description: Optional[str] = None

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/src/imperal_sdk/schemas/imperal.schema.json

@@ -692,6 +692,18 @@
       "default": null,
       "title": "Lifecycle Hooks"
     },
+    "system": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "System"
+    },
     "name": {
       "anyOf": [
         {

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/src/imperal_sdk/validator.py

@@ -7,6 +7,7 @@ Returns structured report with errors, warnings, and info.
 """
 from __future__ import annotations
 
+import os
 import re
 from dataclasses import dataclass, field
 
@@ -706,4 +707,30 @@ def validate_extension(ext) -> ValidationReport:
                     ),
                 ))
 
+    # V31 — `system=True` reserved for first-party Imperal extensions.
+    # System apps are auto-installed for every user, never shown in the
+    # marketplace, and cannot be uninstalled. Allowing a third-party
+    # developer to set this flag would let them slip past discovery and
+    # claim platform-level trust they have not been granted. The Dev Portal
+    # enforces an author allowlist server-side; this validator catches the
+    # mistake locally so the developer sees the error before publish.
+    if bool(getattr(ext, "system", False)):
+        author = (os.environ.get("IMPERAL_AUTHOR_ID") or "").strip()
+        IMPERAL_AUTHOR_IDS = {"imp_u_oPpbwTWjm-"}  # server@webhostmost.com
+        if author and author not in IMPERAL_AUTHOR_IDS:
+            report.issues.append(ValidationIssue(
+                rule="V31", level="ERROR",
+                message=(
+                    f"Extension(system=True) is reserved for first-party "
+                    f"Imperal extensions (admin / billing / developer / "
+                    f"automations). Author {author!r} is not in the Imperal "
+                    f"author allowlist."
+                ),
+                fix=(
+                    "Drop `system=True` from your Extension(...) call. "
+                    "Your app will publish through the normal marketplace "
+                    "flow and users will install it explicitly."
+                ),
+            ))
+
     return report

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/tests/test_cli.py

@@ -14,43 +14,58 @@ def test_cli_version():
 
 
 def test_cli_init_chat_template():
-    """Default chat template generates ChatExtension + ActionResult scaffold."""
+    """Default chat template generates v4-compliant ChatExtension + ActionResult scaffold."""
     runner = CliRunner()
     with runner.isolated_filesystem():
         result = runner.invoke(cli, ["init", "my-test-ext"])
         assert result.exit_code == 0
-        assert "Extension 'my-test-ext' created!" in result.output
+        assert "Extension 'my-test-ext' scaffolded" in result.output
         assert "(template: chat)" in result.output
         assert os.path.exists("my-test-ext/main.py")
+        assert os.path.exists("my-test-ext/icon.svg")  # V21 federal — required
         assert os.path.exists("my-test-ext/requirements.txt")
         assert os.path.exists("my-test-ext/tests/test_main.py")
         assert os.path.exists("my-test-ext/.gitignore")
 
         with open("my-test-ext/main.py") as f:
             content = f.read()
-            assert 'Extension("my-test-ext"' in content
+            assert '"my-test-ext"' in content
             assert "ChatExtension" in content
             assert "ActionResult" in content
             assert 'version="1.0.0"' in content
+            # v4 federal kwargs that v4.1.9 fix added
+            assert "display_name=" in content
+            assert "description=" in content
+            assert "icon=" in content
+            assert "actions_explicit=True" in content
 
         with open("my-test-ext/requirements.txt") as f:
-            assert "imperal-sdk>=1.0.0" in f.read()
+            assert "imperal-sdk>=4.0.0" in f.read()  # v4.1.9 — was >=1.0.0
+
+        with open("my-test-ext/icon.svg") as f:
+            svg = f.read()
+            assert "<svg" in svg
+            assert "viewBox" in svg
 
 
 def test_cli_init_tool_template():
-    """Tool template generates bare @ext.tool scaffold."""
+    """Tool template generates bare @ext.tool scaffold (v4-compliant)."""
     runner = CliRunner()
     with runner.isolated_filesystem():
         result = runner.invoke(cli, ["init", "my-tool-ext", "--template", "tool"])
         assert result.exit_code == 0
         assert "(template: tool)" in result.output
         assert os.path.exists("my-tool-ext/main.py")
+        assert os.path.exists("my-tool-ext/icon.svg")
 
         with open("my-tool-ext/main.py") as f:
             content = f.read()
-            assert 'Extension("my-tool-ext"' in content
+            assert '"my-tool-ext"' in content
             assert "@ext.tool" in content
             assert 'version="1.0.0"' in content
+            # v4 federal kwargs (added in v4.1.9 init scaffold fix)
+            assert "display_name=" in content
+            assert "actions_explicit=True" in content
 
 
 def test_cli_init_invalid_template():

{imperal_sdk-4.1.8 → imperal_sdk-4.2.0}/tests/test_validator.py

@@ -310,3 +310,35 @@ class TestV7NoDirectImports:
         v7_errors = [i for i in report.errors if i.rule == "V7"]
         # This test module does not import anthropic/openai so no V7 error expected
         assert len(v7_errors) == 0
+
+
+class TestV31SystemFlag:
+    """V31 — Extension(system=True) reserved for first-party Imperal authors."""
+
+    def test_system_default_false_no_v31(self, monkeypatch):
+        monkeypatch.setenv("IMPERAL_AUTHOR_ID", "imp_u_random_dev")
+        ext = Extension("hello-3rd", version="1.0.0", display_name="Hello", description="x" * 60, icon="icon.svg")
+        report = validate_extension(ext)
+        assert not [i for i in report.errors if i.rule == "V31"]
+
+    def test_third_party_system_true_blocked(self, monkeypatch):
+        monkeypatch.setenv("IMPERAL_AUTHOR_ID", "imp_u_random_dev")
+        ext = Extension("rogue", version="1.0.0", display_name="Rogue", description="x" * 60, icon="icon.svg", system=True)
+        report = validate_extension(ext)
+        v31 = [i for i in report.errors if i.rule == "V31"]
+        assert len(v31) == 1
+        assert "reserved for first-party" in v31[0].message
+
+    def test_imperal_author_system_true_allowed(self, monkeypatch):
+        monkeypatch.setenv("IMPERAL_AUTHOR_ID", "imp_u_oPpbwTWjm-")
+        ext = Extension("billing", version="1.0.0", display_name="Billing", description="x" * 60, icon="icon.svg", system=True)
+        report = validate_extension(ext)
+        assert not [i for i in report.errors if i.rule == "V31"]
+
+    def test_no_author_env_does_not_block(self, monkeypatch):
+        # Local dev without IMPERAL_AUTHOR_ID set should not fail validation —
+        # Dev Portal enforces author allowlist server-side at publish time.
+        monkeypatch.delenv("IMPERAL_AUTHOR_ID", raising=False)
+        ext = Extension("anything", version="1.0.0", display_name="x", description="x" * 60, icon="icon.svg", system=True)
+        report = validate_extension(ext)
+        assert not [i for i in report.errors if i.rule == "V31"]