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.

refactor(plugins): add WordPress bridge + flagship/multi-blueprint plumbing

Juan Deniseee21d8a1465
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index dcae0977..2d80bdc9 100644
--- a/backend/app/__init__.py
+++ b/backend/app/__init__.py
@@ -500,6 +500,17 @@ def create_app(config_name=None):
import logging as _logging
_logging.getLogger(__name__).warning(f'Legacy secret encryption skipped: {e}')
+ # Seed bundled flagship extensions (D4) — WordPress ships installed by
+ # default on every panel (fresh and upgrade) unless the user uninstalled
+ # it. Done BEFORE load_all_plugins so the loader registers the seeded
+ # blueprints. In-place: no file copy. Best-effort.
+ try:
+ from app.services.plugin_service import seed_flagship_extensions
+ seed_flagship_extensions()
+ except Exception as e:
+ import logging
+ logging.getLogger(__name__).warning(f'Flagship seed: {e}')
+
# Load installed plugins (dynamic blueprints) AFTER migrations,
# so the installed_plugins table exists.
try:
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index ddaf16ce..82157341 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -2100,7 +2100,8 @@ def create_app_db_snapshot(app_id):
return err
from app.models.wordpress_site import DatabaseSnapshot
from app.services.db_sync_service import DatabaseSyncService
- from app.services.wordpress_env_service import WordPressEnvService
+ from app.services.wordpress_bridge import wordpress_env_service
+ WordPressEnvService = wordpress_env_service()
site = _wp_site_for_app(app)
if not site:
return jsonify({'error': 'This application is not a WordPress site'}), 400
diff --git a/backend/app/jobs/builtin_handlers.py b/backend/app/jobs/builtin_handlers.py
index ba1cee05..cd13d7c2 100644
--- a/backend/app/jobs/builtin_handlers.py
+++ b/backend/app/jobs/builtin_handlers.py
@@ -175,7 +175,8 @@ def _prune_old_health_checks():
def check_update_schedules():
from app.models.wordpress_site import WordPressSite, WordPressUpdateRun
- from app.services.wp_update_service import WpUpdateService
+ from app.services.wordpress_bridge import wp_update_service
+ WpUpdateService = wp_update_service()
from datetime import datetime
import json as _json
diff --git a/backend/app/services/__init__.py b/backend/app/services/__init__.py
index a70f8914..d3042313 100644
--- a/backend/app/services/__init__.py
+++ b/backend/app/services/__init__.py
@@ -5,7 +5,10 @@ from app.services.ssl_service import SSLService
from app.services.process_service import ProcessService
from app.services.log_service import LogService
from app.services.php_service import PHPService
-from app.services.wordpress_service import WordPressService
+# NOTE: WordPressService is no longer eagerly imported here. WordPress moved into
+# the bundled ``serverkit-wordpress`` extension (D4); core code that still needs
+# it reaches it lazily via ``app.services.wordpress_bridge`` so core boot never
+# pulls the WordPress stack.
__all__ = [
'SystemService',
@@ -14,5 +17,4 @@ __all__ = [
'ProcessService',
'LogService',
'PHPService',
- 'WordPressService'
]
diff --git a/backend/app/services/backup_policy_service.py b/backend/app/services/backup_policy_service.py
index 59ad8d49..ece465f2 100644
--- a/backend/app/services/backup_policy_service.py
+++ b/backend/app/services/backup_policy_service.py
@@ -338,7 +338,8 @@ class BackupPolicyService:
incremental to a full). Raises on failure."""
meta = {'engine': target['target_type']}
if target['target_type'] == 'wordpress_site':
- from app.services.wordpress_service import WordPressService
+ from app.services.wordpress_bridge import wordpress_service
+ WordPressService = wordpress_service()
result = WordPressService.backup_wordpress(target['root_path'], include_db=True)
if not result.get('success'):
raise BackupPolicyError(result.get('error') or 'WordPress backup failed')
@@ -716,7 +717,8 @@ class BackupPolicyService:
"""Restore a WordPress backup. 'full' (and 'tables', for now) restores
files + database; 'database' imports only the SQL dump; 'files' extracts
only the file archive."""
- from app.services.wordpress_service import WordPressService
+ from app.services.wordpress_bridge import wordpress_service
+ WordPressService = wordpress_service()
meta = run.get_metadata() or {}
backup_dir = run.storage_path
root = target['root_path']
diff --git a/backend/app/services/environment_pipeline_service.py b/backend/app/services/environment_pipeline_service.py
index ae591dd9..9115c4f6 100644
--- a/backend/app/services/environment_pipeline_service.py
+++ b/backend/app/services/environment_pipeline_service.py
@@ -1468,7 +1468,8 @@ class EnvironmentPipelineService:
Returns:
Dict with list of stale environments and cleanup results
"""
- from app.services.git_wordpress_service import GitWordPressService
+ from app.services.wordpress_bridge import git_wordpress_service
+ GitWordPressService = git_wordpress_service()
prod_site = WordPressSite.query.get(production_site_id)
if not prod_site:
diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.py
index 113702be..4ea66c94 100644
--- a/backend/app/services/plugin_service.py
+++ b/backend/app/services/plugin_service.py
@@ -57,6 +57,53 @@ BUILTIN_EXTENSIONS_DIR = os.environ.get(
os.path.join(_PROJECT_ROOT, 'builtin-extensions'),
)
+# Flagship extensions (decision D4): bundled, installed-by-default on EVERY panel
+# (fresh and upgrade), and uninstallable. Unlike the niche Tier-1 conversions
+# (handled one-shot in extension_migration), a flagship is seeded in-place — no
+# file copy — its backend loads straight from builtin-extensions/ and its frontend
+# is pre-bundled (D5). A user uninstall records a marker so it stays gone.
+FLAGSHIP_SLUGS = ['serverkit-wordpress']
+_FLAGSHIP_UNINSTALLED_KEY = 'extensions.flagship_uninstalled'
+
+
+def _ensure_builtin_backend_importable(slug):
+ """Register ``builtin-extensions/<slug>/backend`` as the dashed package
+ ``app.plugins.<slug>`` in ``sys.modules`` (in-place, no copy), so its
+ blueprints and services import — and relative imports inside resolve —
+ without the plugin being copy-installed under ``app/plugins/``.
+
+ This is what makes a dashed, default-installed flagship loadable uniformly in
+ production, dev checkouts, and the test suite. Idempotent; returns ``True`` if
+ the package is (now) importable.
+ """
+ import importlib
+ import importlib.util
+ pkg = f'app.plugins.{slug}'
+ if pkg in sys.modules:
+ return True
+ try:
+ importlib.import_module(pkg) # already copy-installed under app/plugins/
+ return True
+ except ImportError:
+ pass
+ backend_dir = os.path.join(BUILTIN_EXTENSIONS_DIR, slug, 'backend')
+ init_py = os.path.join(backend_dir, '__init__.py')
+ if not os.path.isfile(init_py):
+ return False
+ try:
+ importlib.import_module('app.plugins') # ensure the parent package exists
+ spec = importlib.util.spec_from_file_location(
+ pkg, init_py, submodule_search_locations=[backend_dir]
+ )
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[pkg] = module
+ spec.loader.exec_module(module)
+ return True
+ except Exception as e:
+ logger.warning(f'In-place load of {pkg} failed: {e}')
+ sys.modules.pop(pkg, None)
+ return False
+
def _ensure_backend_dir():
"""Create the backend plugin dir; raise a useful error if we can't."""
@@ -626,6 +673,10 @@ def _attach_status_guard(bp, slug):
guard makes the in-DB status authoritative at request time, so
disabling a plugin actually stops serving its routes.
"""
+ # A blueprint may be mounted at more than one url_prefix (e.g. an alias),
+ # but the guard only needs to run once per blueprint object.
+ if getattr(bp, '_sk_status_guarded', False):
+ return
def _check():
from flask import jsonify
p = InstalledPlugin.query.filter_by(slug=slug).first()
@@ -636,6 +687,43 @@ def _attach_status_guard(bp, slug):
}), 503
return None
bp.before_request(_check)
+ bp._sk_status_guarded = True
+
+
+def _register_extra_blueprints(register, plugin, manifest):
+ """Register a plugin's ``extra_blueprints`` beyond the single ``entry_point``.
+
+ Some extensions (WordPress) expose several blueprints and even mount one
+ blueprint at more than one prefix (a deprecation-window alias). The manifest
+ declares them as::
+
+ "extra_blueprints": [
+ {"module": "wordpress_sites", "attr": "wordpress_sites_bp",
+ "url_prefix": "/api/v1/wordpress"},
+ {"module": "environment_pipeline", "attr": "environment_pipeline_bp",
+ "url_prefix": "/api/v1/wordpress/pipelines",
+ "name": "environment_pipeline_pipelines"}
+ ]
+
+ ``register`` is a ``callable(bp, url_prefix, name=None)`` — either
+ ``current_app.register_blueprint`` (hot-load) or ``app.register_blueprint``
+ (boot). Each blueprint gets the same status guard as the entry blueprint.
+ """
+ import importlib
+ for extra in (manifest or {}).get('extra_blueprints', []):
+ module_name = extra.get('module')
+ attr = extra.get('attr')
+ url_prefix = extra.get('url_prefix')
+ name = extra.get('name')
+ if not (module_name and attr):
+ continue
+ full_module = f'app.plugins.{plugin.slug}.{module_name}'
+ mod = importlib.import_module(full_module)
+ bp = getattr(mod, attr)
+ _attach_status_guard(bp, plugin.slug)
+ register(bp, url_prefix=url_prefix, name=name)
+ logger.info(f'Registered extra blueprint {attr} at {url_prefix}'
+ + (f' (as {name})' if name else ''))
def _register_plugin_blueprint(plugin):
@@ -660,6 +748,8 @@ def _register_plugin_blueprint(plugin):
_attach_status_guard(bp, plugin.slug)
current_app.register_blueprint(bp, url_prefix=plugin.url_prefix)
logger.info(f'Registered blueprint {bp_name} at {plugin.url_prefix}')
+ _register_extra_blueprints(
+ current_app.register_blueprint, plugin, plugin.manifest or {})
except Exception as e:
raise ValueError(f'Failed to register blueprint: {e}')
@@ -745,10 +835,12 @@ def load_all_plugins(app):
app.register_blueprint(bp, url_prefix=plugin.url_prefix)
logger.info(f'Loaded plugin: {plugin.display_name} v{plugin.version} at {plugin.url_prefix}')
+ manifest = plugin.manifest or {}
+ _register_extra_blueprints(app.register_blueprint, plugin, manifest)
+
# Re-establish the plugin's data models, jobs, and socket
# namespace on boot (install-time registration doesn't survive
# a restart).
- manifest = plugin.manifest or {}
try:
from app.services import extension_lifecycle
extension_lifecycle.register_models(plugin, manifest)
@@ -794,15 +886,22 @@ def uninstall_plugin(plugin_id, purge=False):
# Drop any AI tools/context this plugin contributed to the assistant.
_unregister_plugin_ai(slug)
- # Remove backend files
- backend_dest = os.path.join(BACKEND_PLUGINS_DIR, slug)
- if os.path.exists(backend_dest):
- shutil.rmtree(backend_dest)
+ if slug in FLAGSHIP_SLUGS:
+ # Flagships live in-place (backend in builtin-extensions/, frontend
+ # pre-bundled under src/plugins/ — both tracked in the repo). Never delete
+ # those; just record the user's choice so the boot seed leaves it out, and
+ # drop the row (the status guard 503s any still-registered routes).
+ _set_flagship_uninstalled(slug, True)
+ else:
+ # Remove backend files
+ backend_dest = os.path.join(BACKEND_PLUGINS_DIR, slug)
+ if os.path.exists(backend_dest):
+ shutil.rmtree(backend_dest)
- # Remove frontend files
- frontend_dest = os.path.join(FRONTEND_PLUGINS_DIR, slug)
- if os.path.exists(frontend_dest):
- shutil.rmtree(frontend_dest)
+ # Remove frontend files
+ frontend_dest = os.path.join(FRONTEND_PLUGINS_DIR, slug)
+ if os.path.exists(frontend_dest):
+ shutil.rmtree(frontend_dest)
db.session.delete(plugin)
db.session.commit()
@@ -1057,6 +1156,29 @@ def install_builtin_extension(slug, user_id=None):
if not os.path.isdir(BUILTIN_EXTENSIONS_DIR):
raise ValueError(f'Builtin extensions dir not found: {BUILTIN_EXTENSIONS_DIR}')
+ # Flagships (D4) re-install in-place: clear the user-uninstall marker and
+ # re-seed the active row — no file copy, since the backend loads from
+ # builtin-extensions/ and the frontend is pre-bundled.
+ if slug in FLAGSHIP_SLUGS:
+ _set_flagship_uninstalled(slug, False)
+ for entry in list_builtin_extensions():
+ if entry['slug'] == slug:
+ _ensure_builtin_backend_importable(slug)
+ existing = InstalledPlugin.query.filter_by(slug=slug).first()
+ if existing:
+ existing.status = InstalledPlugin.STATUS_ACTIVE
+ db.session.commit()
+ return existing
+ plugin = _seed_flagship_row(entry)
+ try:
+ _register_plugin_blueprint(plugin)
+ except Exception as e:
+ logger.warning(
+ f'Flagship blueprint hot-load failed for {slug} '
+ f'(will load on restart): {e}')
+ return plugin
+ raise ValueError(f"No builtin extension with slug '{slug}'")
+
for entry in list_builtin_extensions():
if entry['slug'] == slug:
return install_from_path(entry['path'], user_id=user_id)
@@ -1064,6 +1186,113 @@ def install_builtin_extension(slug, user_id=None):
raise ValueError(f"No builtin extension with slug '{slug}'")
+# ── Flagship (D4) default-install machinery ──
+
+def _flagship_uninstalled_set():
+ """Slugs the user explicitly uninstalled — never re-seeded on boot."""
+ from app.services.settings_service import SettingsService
+ raw = SettingsService.get(_FLAGSHIP_UNINSTALLED_KEY, '')
+ if not raw:
+ return set()
+ try:
+ return set(json.loads(raw))
+ except (ValueError, TypeError):
+ return {s.strip() for s in str(raw).split(',') if s.strip()}
+
+
+def _set_flagship_uninstalled(slug, uninstalled):
+ from app.services.settings_service import SettingsService
+ current = _flagship_uninstalled_set()
+ if uninstalled:
+ current.add(slug)
+ else:
+ current.discard(slug)
+ SettingsService.set(_FLAGSHIP_UNINSTALLED_KEY, json.dumps(sorted(current)))
+
+
+def _seed_flagship_row(entry):
+ """Create an active InstalledPlugin row for a flagship without copying files.
+
+ The backend is loaded in-place from builtin-extensions/ (see
+ ``_ensure_builtin_backend_importable``) and the frontend is pre-bundled under
+ ``frontend/src/plugins/<slug>`` (D5), so the row only records install state
+ for the Marketplace/contributions surfaces and drives the status guard.
+ """
+ manifest = entry['manifest']
+ slug = entry['slug']
+ has_backend = os.path.isdir(os.path.join(entry['path'], 'backend'))
+ has_frontend = os.path.isdir(os.path.join(entry['path'], 'frontend'))
+
+ plugin = InstalledPlugin(
+ name=manifest['name'],
+ display_name=manifest.get('display_name', slug),
+ slug=slug,
+ version=manifest['version'],
+ description=manifest.get('description', ''),
+ author=manifest.get('author', ''),
+ homepage=manifest.get('homepage', ''),
+ repository=manifest.get('repository', ''),
+ license=manifest.get('license', ''),
+ category=manifest.get('category', 'utility'),
+ source_type='builtin',
+ status=InstalledPlugin.STATUS_ACTIVE,
+ )
+ plugin.manifest = manifest
+ plugin.has_backend = has_backend
+ plugin.has_frontend = has_frontend
+ plugin.backend_path = f'builtin-extensions/{slug}/backend' if has_backend else None
+ plugin.frontend_path = f'src/plugins/{slug}' if has_frontend else None
+ plugin.entry_point = manifest.get('entry_point', '')
+ plugin.url_prefix = manifest.get('url_prefix', f'/api/v1/{slug}')
+ plugin.frontend_entry = manifest.get('frontend_entry', '')
+ db.session.add(plugin)
+ db.session.commit()
+
+ # Register plugin-owned data models / jobs / sockets, same as a copy-install.
+ try:
+ from app.services import extension_lifecycle
+ extension_lifecycle.register_models(plugin, manifest)
+ extension_lifecycle.register_jobs(plugin, manifest)
+ from app.plugins_sdk import sockets as _ext_sockets
+ _ext_sockets.register_from_manifest(plugin, manifest)
+ except Exception as e:
+ logger.warning(f'Flagship lifecycle setup for {slug}: {e}')
+
+ _refresh_plugin_ai(plugin)
+ try:
+ _regenerate_frontend_manifest()
+ except Exception as e:
+ logger.warning(f'Frontend manifest regen after flagship seed for {slug}: {e}')
+ logger.info(f'Seeded flagship extension row: {slug} v{manifest["version"]}')
+ return plugin
+
+
+def seed_flagship_extensions():
+ """Ensure bundled flagship extensions (D4) have an active row on EVERY panel
+ — fresh AND upgrade — unless the user explicitly uninstalled them.
+
+ Called from ``create_app`` right before ``load_all_plugins`` so the loader
+ picks up the seeded row and registers the blueprints (in-place). Best-effort.
+ """
+ uninstalled = _flagship_uninstalled_set()
+ available = {e['slug']: e for e in list_builtin_extensions()}
+ for slug in FLAGSHIP_SLUGS:
+ if slug in uninstalled:
+ continue
+ entry = available.get(slug)
+ if not entry:
+ continue
+ # Make the backend importable in-place regardless (the bridge and the
+ # loader both rely on app.plugins.<slug> resolving).
+ _ensure_builtin_backend_importable(slug)
+ if InstalledPlugin.query.filter_by(slug=slug).first():
+ continue
+ try:
+ _seed_flagship_row(entry)
+ except Exception as e:
+ logger.warning(f'Flagship seed for {slug} failed (retry next boot): {e}')
+
+
def _assert_panel_compatible(entry):
"""Raise if the panel version is outside an entry's min/max_panel_version."""
from app.utils.version import version_satisfies, get_panel_version
diff --git a/backend/app/services/preview_service.py b/backend/app/services/preview_service.py
index ef58fe4e..b4f6f4dd 100644
--- a/backend/app/services/preview_service.py
+++ b/backend/app/services/preview_service.py
@@ -316,8 +316,9 @@ class PreviewService:
try:
if getattr(app, 'app_type', None) == 'wordpress':
try:
- from app.services.wordpress_service import WordPressService
+ from app.services.wordpress_bridge import wordpress_service
from app.models.wordpress_site import WordPressSite
+ WordPressService = wordpress_service()
site = WordPressSite.query.filter_by(application_id=app.id).first()
if site:
res = WordPressService.create_preview_instance(
@@ -358,8 +359,9 @@ class PreviewService:
# Best-effort WordPress teardown.
if app is not None and getattr(app, 'app_type', None) == 'wordpress':
try:
- from app.services.wordpress_service import WordPressService
+ from app.services.wordpress_bridge import wordpress_service
from app.models.wordpress_site import WordPressSite
+ WordPressService = wordpress_service()
site = WordPressSite.query.filter_by(application_id=app.id).first()
if site:
WordPressService.destroy_preview_instance(site, preview.pr_number)
diff --git a/backend/app/services/webhook_service.py b/backend/app/services/webhook_service.py
index 4acab81c..b86cee9a 100644
--- a/backend/app/services/webhook_service.py
+++ b/backend/app/services/webhook_service.py
@@ -420,7 +420,8 @@ class WebhookService:
# WordPressSite whose connected repo+branch matches the push.
try:
from app.models.wordpress_site import WordPressSite
- from app.services.git_wordpress_service import GitWordPressService
+ from app.services.wordpress_bridge import git_wordpress_service
+ GitWordPressService = git_wordpress_service()
pushed_norm = cls._normalize_repo_url(webhook.source_repo_url)
wp_deployed = 0
diff --git a/backend/app/services/wordpress_bridge.py b/backend/app/services/wordpress_bridge.py
new file mode 100644
index 00000000..371267cc
--- /dev/null
+++ b/backend/app/services/wordpress_bridge.py
@@ -0,0 +1,82 @@
+"""Importlib bridge to the ``serverkit-wordpress`` extension backend.
+
+WordPress ships as a bundled, default-installed, uninstallable extension (D4).
+Its backend lives in ``builtin-extensions/serverkit-wordpress/backend/`` and is
+loaded as the *dashed* package ``app.plugins.serverkit-wordpress``. Because the
+slug contains a dash it can never be reached with a normal ``import`` statement
+(``import app.plugins.serverkit-wordpress`` is a SyntaxError), so the handful of
+core call sites that still reach into the WordPress stack go through this bridge,
+which resolves modules with ``importlib`` on a *string* path — dash-safe.
+
+Loadability is uniform across prod / dev / test:
+
+* **Copy-installed** (``app/plugins/serverkit-wordpress`` exists) — the ordinary
+ path-based finder resolves it, same as any marketplace plugin.
+* **In-place** (dev checkout, the test suite, or a fresh boot *before* the
+ flagship seed row is created) — we register the builtin backend directory in
+ ``sys.modules`` as the package via ``spec_from_file_location`` with
+ ``submodule_search_locations`` pointing at it, so both submodule and relative
+ imports inside the extension resolve. **No file copy is required.** This is
+ what makes a dashed, default-installed package loadable everywhere.
+
+During the two-speed migration window the bridge also falls back to the legacy
+core location (``app.services.<module>``) so callers can be re-pointed *before*
+the physical move lands without breaking. Once the files move, the extension
+path wins and the fallback is simply never reached.
+"""
+import importlib
+
+SLUG = 'serverkit-wordpress'
+PKG = f'app.plugins.{SLUG}'
+
+
+def ensure_loadable():
+ """Make ``app.plugins.serverkit-wordpress`` importable, in-place if needed.
+
+ Delegates to the canonical in-place loader in ``plugin_service`` (shared with
+ the flagship boot path). Idempotent and cheap after the first call. Returns
+ ``True`` if the package is (now) importable, ``False`` if the extension isn't
+ present on disk at all (in which case callers fall back to the legacy core
+ location during the migration window).
+ """
+ from app.services.plugin_service import _ensure_builtin_backend_importable
+ return _ensure_builtin_backend_importable(SLUG)
+
+
+def load(module_name):
+ """Import a module from the extension backend (e.g. ``'wordpress_service'``).
+
+ Falls back to the legacy core location during the migration window.
+ """
+ if ensure_loadable():
+ try:
+ return importlib.import_module(f'{PKG}.{module_name}')
+ except ImportError:
+ pass
+ # Two-speed fallback: the file may still live in core (pre-move).
+ return importlib.import_module(f'app.services.{module_name}')
+
+
+def get(module_name, attr):
+ """Return an attribute (usually a service class) from an extension module."""
+ return getattr(load(module_name), attr)
+
+
+# ── Convenience accessors for the service classes core code reaches for ──
+# All WordPress *models* stay core (app.models.wordpress_site / wordpress_custom_plugin);
+# only these services physically move into the extension, so only these need the bridge.
+
+def wordpress_service():
+ return get('wordpress_service', 'WordPressService')
+
+
+def git_wordpress_service():
+ return get('git_wordpress_service', 'GitWordPressService')
+
+
+def wordpress_env_service():
+ return get('wordpress_env_service', 'WordPressEnvService')
+
+
+def wp_update_service():
+ return get('wp_update_service', 'WpUpdateService')