Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(marketplace): surface registry v2 logo/repo/bundled fields

Juan Denisc7b12b3095e0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 447e1d6b..d9ec6632 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,18 @@ and the project aims to follow [Semantic Versioning](https://semver.org/spec/v2.
The `dev` branch is well ahead of the last `main` release. The headline work
awaiting a stable release:
+### Added
+
+- **Public extension index (registry v2)** — the extension registry schema gains
+ optional `logo`, `repo`, and `bundled` fields (additive; v1 entries stay
+ valid). The Marketplace now surfaces extension logos (shown first in the art
+ fallback chain) and a **Source repo** link on the detail modal. Builtin
+ extensions are published to the public index as `bundled` catalog listings
+ (generated via `scripts/export-registry-entries.mjs`) so the index is the full
+ catalog of every extension; bundled entries stay out of the Browse merge to
+ avoid duplicating builtin cards (`GET /api/v1/marketplace/registry?include_bundled=true`
+ returns the complete set).
+
### Changed
- **UI consistency round (Jobs, Queue Bus, Email, Marketplace)** — brought four
diff --git a/backend/app/api/marketplace.py b/backend/app/api/marketplace.py
index 76a8db9d..9c33e8fa 100644
--- a/backend/app/api/marketplace.py
+++ b/backend/app/api/marketplace.py
@@ -6,7 +6,7 @@ third lane that was redundant with the three real sources — the builtin
folder scan (``/plugins/builtin``), the remote registry (below), and live
``InstalledPlugin`` state. This blueprint now serves only the registry.
"""
-from flask import Blueprint, jsonify
+from flask import Blueprint, jsonify, request
from flask_jwt_extended import jwt_required
from app.services.audit_service import AuditService
from app.models.audit_log import AuditLog
@@ -24,10 +24,15 @@ def get_current_user():
@jwt_required()
def list_registry():
"""Return the remote-registry extensions (with live install state), for the
- Browse merge. Read-only; offline-tolerant (falls back to a bundled index)."""
+ Browse merge. Read-only; offline-tolerant (falls back to a bundled index).
+
+ Bundled entries (builtins listed for the public catalog) are excluded by
+ default to avoid duplicating the builtin cards; pass
+ ``?include_bundled=true`` for the complete catalog."""
from app.services import registry_service
+ include_bundled = request.args.get('include_bundled', '').lower() in ('1', 'true', 'yes')
return jsonify({
- 'extensions': registry_service.list_catalog(),
+ 'extensions': registry_service.list_catalog(include_bundled=include_bundled),
'source': registry_service.registry_source_label(),
})
diff --git a/backend/app/data/registry_index.json b/backend/app/data/registry_index.json
index 696ab924..82fe1dc9 100644
--- a/backend/app/data/registry_index.json
+++ b/backend/app/data/registry_index.json
@@ -1,6 +1,6 @@
{
- "schema_version": 1,
- "updated": "2026-07-01",
+ "schema_version": 2,
+ "updated": "2026-07-09",
"note": "Bundled fallback copy of the ServerKit extension registry index. The live index is fetched from SERVERKIT_REGISTRY_URL when configured; this file is used offline and in tests. Curated via PR in the serverkit-extensions repo.",
"extensions": [
{
@@ -17,6 +17,8 @@
"sdk_version": "^1.0.0",
"source": "https://github.com/jhd3197/serverkit-gui",
"sha256": null,
+ "repo": "https://github.com/jhd3197/serverkit-gui",
+ "logo": "https://raw.githubusercontent.com/jhd3197/serverkit-extensions/main/assets/serverkit-gui/logo.svg",
"homepage": "https://github.com/jhd3197/serverkit-gui",
"icon": "<rect x=\"2\" y=\"3\" width=\"20\" height=\"14\" rx=\"2\"/><line x1=\"8\" y1=\"21\" x2=\"16\" y2=\"21\"/><line x1=\"12\" y1=\"17\" x2=\"12\" y2=\"21\"/>",
"screenshots": []
diff --git a/backend/app/services/registry_service.py b/backend/app/services/registry_service.py
index c1b71a58..1d6091b0 100644
--- a/backend/app/services/registry_service.py
+++ b/backend/app/services/registry_service.py
@@ -17,6 +17,7 @@ import json
import logging
import os
import time
+from urllib.parse import urljoin
import requests
@@ -50,7 +51,10 @@ except ValueError:
# Module-level cache: last successfully-parsed entry list + when we fetched it.
_cache = {'ts': 0.0, 'entries': None, 'source': None}
-# Fields we surface for a registry entry, with defaults.
+# Fields we surface for a registry entry, with defaults. Index v2 adds
+# `repo`, `logo`, and `bundled` (see the serverkit-extensions schema); any
+# field not listed here is stripped before it reaches the UI, so new index
+# fields must be registered below to survive normalization.
_FIELDS = {
'slug': '',
'display_name': '',
@@ -59,18 +63,35 @@ _FIELDS = {
'category': 'utility',
'author': '',
'first_party': False,
+ 'bundled': False,
'permissions': [],
'min_panel_version': None,
'max_panel_version': None,
'source': '',
'sha256': None,
+ 'repo': '',
+ 'logo': None,
'homepage': '',
'icon': None,
'screenshots': [],
}
-def _normalize(raw):
+def _resolve_logo(logo, base_url):
+ """Turn a repo-relative logo path (``assets/<slug>/<file>``) into an
+ absolute URL against the index we fetched it from. Absolute https logos
+ pass through unchanged; ``urljoin`` resolves both the raw-GitHub index
+ (→ raw asset URL) and the serverkit.ai ``/ext/index.json`` (→ proxy URL)."""
+ if not logo or not isinstance(logo, str):
+ return logo
+ if logo.startswith('http://') or logo.startswith('https://'):
+ return logo
+ if base_url:
+ return urljoin(base_url, logo)
+ return logo
+
+
+def _normalize(raw, base_url=None):
if not isinstance(raw, dict) or not raw.get('slug'):
return None
out = {}
@@ -80,20 +101,24 @@ def _normalize(raw):
out['permissions'] = []
if not isinstance(out['screenshots'], list):
out['screenshots'] = []
+ out['bundled'] = bool(out['bundled'])
+ out['logo'] = _resolve_logo(out['logo'], base_url)
return out
-def _read_index_payload(payload):
+def _read_index_payload(payload, base_url=None):
exts = payload.get('extensions') if isinstance(payload, dict) else None
if not isinstance(exts, list):
return []
- return [e for e in (_normalize(x) for x in exts) if e]
+ return [e for e in (_normalize(x, base_url) for x in exts) if e]
def _load_bundled():
try:
with open(_BUNDLED_INDEX, 'r', encoding='utf-8') as f:
- return _read_index_payload(json.load(f))
+ # Bundled copy mirrors the public index; resolve its relative logos
+ # against the default (raw-GitHub) index base.
+ return _read_index_payload(json.load(f), base_url=DEFAULT_REGISTRY_URL)
except Exception as e:
logger.warning(f'Could not read bundled registry index: {e}')
return []
@@ -108,7 +133,7 @@ def _fetch_remote():
'User-Agent': 'ServerKit-Registry/1.0',
})
resp.raise_for_status()
- return _read_index_payload(resp.json())
+ return _read_index_payload(resp.json(), base_url=url)
def refresh(force=False):
@@ -170,8 +195,18 @@ def to_catalog_dict(entry):
return d
-def list_catalog():
- return [to_catalog_dict(e) for e in refresh()]
+def list_catalog(include_bundled=False):
+ """Registry entries + live install state for the Marketplace Browse merge.
+
+ Bundled entries (``bundled: true``) are catalog listings for extensions
+ that ship inside the panel — the Browse tab already renders those from
+ ``list_builtin_extensions()``, so a bundled index entry would duplicate
+ the card. They are excluded by default; pass ``include_bundled=True`` to
+ get the complete catalog (e.g. for the public gallery API)."""
+ entries = refresh()
+ if not include_bundled:
+ entries = [e for e in entries if not e.get('bundled')]
+ return [to_catalog_dict(e) for e in entries]
def registry_source_label():
diff --git a/backend/tests/test_registry.py b/backend/tests/test_registry.py
index 1f59d46f..3283bbca 100644
--- a/backend/tests/test_registry.py
+++ b/backend/tests/test_registry.py
@@ -258,3 +258,86 @@ def test_registry_url_empty_disables_remote(monkeypatch):
def test_registry_url_env_override_wins(monkeypatch):
monkeypatch.setenv('SERVERKIT_REGISTRY_URL', 'https://example.test/index.json')
assert registry_service._registry_url() == 'https://example.test/index.json'
+
+
+# --------------------------------------------------------------------------- #
+# Index v2 fields — logo / repo / bundled
+# --------------------------------------------------------------------------- #
+
+def test_v2_entry_normalizes_logo_and_repo():
+ """A v2 entry keeps logo/repo; an absolute logo passes through unchanged."""
+ e = registry_service._normalize({
+ 'slug': 'gui', 'display_name': 'GUI', 'version': '1.0.0',
+ 'source': 'https://x/gui.zip',
+ 'repo': 'https://github.com/acme/gui',
+ 'logo': 'https://cdn.example/gui.svg',
+ })
+ assert e['repo'] == 'https://github.com/acme/gui'
+ assert e['logo'] == 'https://cdn.example/gui.svg'
+ assert e['bundled'] is False
+
+
+def test_relative_logo_resolved_against_index_base():
+ """A repo-relative logo becomes absolute against the index URL it came
+ from (raw-GitHub index → raw asset URL)."""
+ base = registry_service.DEFAULT_REGISTRY_URL # .../main/index.json
+ e = registry_service._normalize({
+ 'slug': 'gui', 'display_name': 'GUI', 'version': '1.0.0',
+ 'source': 'https://x/gui.zip',
+ 'logo': 'assets/gui/logo.svg',
+ }, base_url=base)
+ assert e['logo'] == (
+ 'https://raw.githubusercontent.com/jhd3197/serverkit-extensions/'
+ 'main/assets/gui/logo.svg'
+ )
+
+
+def test_v1_entry_unaffected_by_v2_defaults():
+ """An entry with no v2 fields normalizes with safe defaults."""
+ e = registry_service._normalize({
+ 'slug': 'old', 'display_name': 'Old', 'version': '1.0.0',
+ 'source': 'https://x/old.zip',
+ })
+ assert e['bundled'] is False
+ assert e['repo'] == ''
+ assert e['logo'] is None
+
+
+def test_bundled_excluded_from_catalog_by_default(app, monkeypatch):
+ monkeypatch.setattr(registry_service, '_cache', {
+ 'ts': 9e18, 'source': 'test',
+ 'entries': [
+ registry_service._normalize({
+ 'slug': 'community-ext', 'display_name': 'Community', 'version': '1.0.0',
+ 'source': 'https://x/c.zip',
+ }),
+ registry_service._normalize({
+ 'slug': 'serverkit-wordpress', 'display_name': 'WordPress',
+ 'version': '1.0.0', 'bundled': True,
+ }),
+ ],
+ })
+ default_slugs = {e['slug'] for e in registry_service.list_catalog()}
+ assert 'community-ext' in default_slugs
+ assert 'serverkit-wordpress' not in default_slugs # bundled hidden from Browse
+
+ full_slugs = {e['slug'] for e in registry_service.list_catalog(include_bundled=True)}
+ assert 'serverkit-wordpress' in full_slugs
+ assert 'community-ext' in full_slugs
+
+
+def test_registry_endpoint_include_bundled_flag(app, client, auth_headers, monkeypatch):
+ monkeypatch.setattr(registry_service, '_cache', {
+ 'ts': 9e18, 'source': 'test',
+ 'entries': [
+ registry_service._normalize({
+ 'slug': 'serverkit-wordpress', 'display_name': 'WordPress',
+ 'version': '1.0.0', 'bundled': True,
+ }),
+ ],
+ })
+ resp = client.get('/api/v1/marketplace/registry', headers=auth_headers)
+ assert not any(e['slug'] == 'serverkit-wordpress' for e in resp.get_json()['extensions'])
+
+ resp2 = client.get('/api/v1/marketplace/registry?include_bundled=true', headers=auth_headers)
+ assert any(e['slug'] == 'serverkit-wordpress' for e in resp2.get_json()['extensions'])
diff --git a/docs/EXTENSIONS_REGISTRY.md b/docs/EXTENSIONS_REGISTRY.md
index 4bf4fec1..c61892f8 100644
--- a/docs/EXTENSIONS_REGISTRY.md
+++ b/docs/EXTENSIONS_REGISTRY.md
@@ -35,27 +35,33 @@ Relevant endpoints:
---
-## `index.json` format (schema_version 1)
+## `index.json` format (schema_version 2)
+
+`schema_version` is now `1` **or** `2`. Version 2 is fully additive — v1 entries
+stay valid unchanged; the new fields (`logo`, `repo`, `bundled`) are optional.
```jsonc
{
- "schema_version": 1,
- "updated": "2026-07-01",
+ "schema_version": 2,
+ "updated": "2026-07-09",
"extensions": [
{
"slug": "serverkit-gui", // required — matches the manifest name
"display_name": "ServerKit Agent GUI", // required
"description": "…",
- "version": "0.1.0", // required — the published version
+ "version": "0.1.0", // required (unless bundled) — the published version
"category": "monitoring", // ai|monitoring|security|deployment|integration|ui|utility
"author": "Juan Denis",
"first_party": false, // true only for ServerKit-authored entries
+ "bundled": false, // v2 — true = ships inside the panel (catalog listing only)
"permissions": ["network"], // declared host permissions (honesty is reviewed)
"min_panel_version": "1.7.0", // optional compat gate (inclusive)
"max_panel_version": null, // optional
"sdk_version": "^1.0.0", // optional (additive) — frontend SDK range the bundle targets
"source": "https://github.com/owner/repo", // repo URL (latest release), release URL, or direct .zip
"sha256": "…", // sha256 of the release zip — STRONGLY recommended
+ "repo": "https://github.com/owner/repo", // v2 — https URL of the source repo (shown as "Source repo")
+ "logo": "assets/serverkit-gui/logo.svg", // v2 — https URL OR repo-relative assets/<slug>/<file>
"release_notes": "…", // optional (additive) — shown in the update-diff modal
"homepage": "https://…",
"icon": "<svg-inner-markup/>", // rendered on the detail view
@@ -79,6 +85,28 @@ Notes:
- `release_notes` (additive) is free text shown in the Marketplace **update-diff**
modal alongside the version + permissions delta. Old panels ignore it.
+### v2 fields (`logo`, `repo`, `bundled`)
+
+- **`logo`** — an extension logo, shown first in the Marketplace art fallback
+ chain (before brand marks / generated covers). Either an absolute `https://`
+ URL or a **repo-relative** path `assets/<slug>/<file>` (`.svg` or `.png`,
+ ≤ 200 KB) committed to the `serverkit-extensions` repo alongside the entry.
+ Repo-relative paths are resolved to absolute URLs by the panel (against the
+ index URL it fetched) and rewritten by the serverkit.ai `/ext` endpoint, so a
+ single relative path works whether the panel reads the raw-GitHub index or the
+ domain.
+- **`repo`** — the https URL of the extension's source repository. The detail
+ modal renders it as a **"Source repo"** link.
+- **`bundled`** — `true` marks an entry as one of the panel's builtin
+ extensions. Bundled entries are **catalog listings only** (they ship inside
+ the panel, so `source`/`sha256` are optional) and are **excluded from the
+ Browse merge** by default to avoid duplicating the builtin cards; the API
+ exposes them via `GET /api/v1/marketplace/registry?include_bundled=true`.
+ Generate them from the panel repo — never hand-type:
+ ```bash
+ node scripts/export-registry-entries.mjs # emits index-v2 bundled entries
+ ```
+
---
## Publishing an extension
diff --git a/frontend/src/pages/Marketplace.jsx b/frontend/src/pages/Marketplace.jsx
index 7d626c78..873875ad 100644
--- a/frontend/src/pages/Marketplace.jsx
+++ b/frontend/src/pages/Marketplace.jsx
@@ -4,6 +4,7 @@ import {
Activity,
CheckCircle2,
DownloadCloud,
+ ExternalLink,
LayoutGrid,
Package,
PackageCheck,
@@ -85,6 +86,7 @@ const getRegistryCatalogEntry = (entry) => ({
firstParty: isFirstParty(entry.author, entry),
icon: entry.icon || null,
logo: entry.logo || null,
+ repo: entry.repo || entry.homepage || null,
screenshots: Array.isArray(entry.screenshots) ? entry.screenshots : [],
permissions: Array.isArray(entry.permissions) ? entry.permissions : [],
configSchema: entry.config_schema && typeof entry.config_schema === 'object' ? entry.config_schema : null,
@@ -655,6 +657,17 @@ const ExtensionDetailModal = ({ entry, installing, statusVariant, onClose, onIns
<span>v{entry.version}</span>
{entry.author && <span>by {entry.author}</span>}
<span>{isLocal ? 'built-in' : entry.extensionType}</span>
+ {entry.repo && (
+ <a
+ href={entry.repo}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="extension-detail__repo-link"
+ >
+ <ExternalLink aria-hidden="true" />
+ Source repo
+ </a>
+ )}
</div>
</div>
</div>
diff --git a/frontend/src/styles/pages/_marketplace.scss b/frontend/src/styles/pages/_marketplace.scss
index 7faf7c19..c6f51d91 100644
--- a/frontend/src/styles/pages/_marketplace.scss
+++ b/frontend/src/styles/pages/_marketplace.scss
@@ -484,6 +484,23 @@
font-size: $font-size-sm;
}
+ &__repo-link {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-1;
+ color: $accent-primary;
+ text-decoration: none;
+
+ svg {
+ width: 14px;
+ height: 14px;
+ }
+
+ &:hover {
+ text-decoration: underline;
+ }
+ }
+
&__desc {
margin: 0;
color: $text-secondary;