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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat: add declarative walkthrough contribution contract
Juan Deniscfcf965e2442
diff --git a/backend/app/api/plugins.py b/backend/app/api/plugins.pyindex 222cff78..66d74e47 100644--- a/backend/app/api/plugins.py+++ b/backend/app/api/plugins.py@@ -481,6 +481,10 @@ def get_manifest_spec():'description': 'Placeable dashboard widget types: {id, name, component, icon?, category?, description?, w?, h?, min?, default_cfg?}. Unlike widgets (fixed host slot), these appear in the dashboard widget library and the user positions, resizes and configures instances of them.'},'layouts': {'type': 'array','description': 'Custom layout components: {id, component}. The component must render <Outlet/> somewhere; it wraps every route that references its id. Built-in layouts (padded, full, bare) are reserved.'},+ 'walkthroughs': {+ 'type': 'array',+ 'description': 'Declarative guided flows: {id, title, description, duration?, icon?, tone?, secondary?, permissions?, steps}. Steps use stable data-walkthrough target tokens and completion {type: manual|route|signal|check|target, ...}. Definitions are namespaced to the contributing extension at runtime and cannot contain executable code.',+ },},},},diff --git a/backend/app/api/walkthroughs.py b/backend/app/api/walkthroughs.pyindex 43686c30..f4ac3dff 100644--- a/backend/app/api/walkthroughs.py+++ b/backend/app/api/walkthroughs.py@@ -2,7 +2,11 @@from flask import Blueprint, jsonify, request-from app.middleware.rbac import get_current_user, require_role, viewer_required+from app.middleware.rbac import admin_required, get_current_user, require_role, viewer_required+from app.services.walkthrough_definition_service import (+ WalkthroughDefinitionError,+ WalkthroughDefinitionService,+)from app.services.walkthrough_service import (WalkthroughService,WalkthroughStateError,@@ -29,3 +33,24 @@ def update_walkthrough_state():except WalkthroughStateError as exc:return jsonify({'error': str(exc)}), 400return jsonify({'success': True, 'state': state}), 200+++@walkthroughs_bp.route('/definitions', methods=['GET'])+@viewer_required+def get_walkthrough_definitions():+ return jsonify({+ 'definitions': WalkthroughDefinitionService.get_definitions(),+ }), 200+++@walkthroughs_bp.route('/definitions', methods=['PUT'])+@admin_required+def update_walkthrough_definitions():+ data = request.get_json(silent=True) or {}+ try:+ definitions = WalkthroughDefinitionService.save_definitions(+ data.get('definitions', data),+ )+ except WalkthroughDefinitionError as exc:+ return jsonify({'error': str(exc)}), 400+ return jsonify({'success': True, 'definitions': definitions}), 200diff --git a/backend/app/services/contribution_service.py b/backend/app/services/contribution_service.pyindex 8eec9d5a..d60bd3af 100644--- a/backend/app/services/contribution_service.py+++ b/backend/app/services/contribution_service.py@@ -12,7 +12,8 @@ A plugin manifest may declare a `contributions` block with any subset of:"dashboard_widgets": [{ id, name, component, icon?, category?,description?, w?, h?, min?, default_cfg? }],"layouts": [{ id, component }],- "tabs": [{ group, to, label, icon?, end?, order? }]+ "tabs": [{ group, to, label, icon?, end?, order? }],+ "walkthroughs": [{ id, title, description, steps, ... }]}`widgets` and `dashboard_widgets` are different surfaces and are easy to@@ -113,6 +114,7 @@ def get_active_contributions():dashboard_widgets = []layouts = []tabs = []+ walkthroughs = []# AI assistant contributions: per-route suggested prompts + custom# tool-result renderers, consumed by the core AIAssistant.ai = {'suggested_prompts': [], 'tool_renderers': []}@@ -129,6 +131,7 @@ def get_active_contributions():dashboard_widgets.extend(_tag(contrib.get('dashboard_widgets'), p.slug))layouts.extend(_tag(contrib.get('layouts'), p.slug))tabs.extend(_tag(contrib.get('tabs'), p.slug))+ walkthroughs.extend(_tag(contrib.get('walkthroughs'), p.slug))ai_contrib = contrib.get('ai')if isinstance(ai_contrib, dict):@@ -150,6 +153,7 @@ def get_active_contributions():'dashboard_widgets': dashboard_widgets,'layouts': layouts,'tabs': tabs,+ 'walkthroughs': walkthroughs,'ai': ai,# Panel SDK version the client uses to gate runtime bundles (plan 25 #1).'sdk_version': SDK_VERSION,diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.pyindex d09002f3..8ebb3843 100644--- a/backend/app/services/plugin_service.py+++ b/backend/app/services/plugin_service.py@@ -443,6 +443,7 @@ _REQUIRED_CONTRIB_KEYS = {'widgets': ('slot', 'component'),'dashboard_widgets': ('id', 'name', 'component'),'layouts': ('id', 'component'),+ 'walkthroughs': ('id', 'title', 'description', 'steps'),}_KNOWN_CONTRIB_KINDS = set(_REQUIRED_CONTRIB_KEYS) | {'page_titles', 'ai'}@@ -534,6 +535,16 @@ def _validate_manifest(manifest):if titles is not None and not isinstance(titles, dict):problems.append('contributions.page_titles must be an object of path -> title')+ walkthroughs = contrib.get('walkthroughs')+ if walkthroughs is not None:+ from app.services.walkthrough_definition_service import (+ validate_walkthrough_definitions,+ )+ problems.extend(validate_walkthrough_definitions(+ walkthroughs,+ field='contributions.walkthroughs',+ ))+if problems:raise ValueError('Manifest validation failed: ' + '; '.join(problems)diff --git a/backend/app/services/walkthrough_definition_service.py b/backend/app/services/walkthrough_definition_service.pynew file mode 100644index 00000000..bbb15878--- /dev/null+++ b/backend/app/services/walkthrough_definition_service.py@@ -0,0 +1,206 @@+"""Validation and storage for declarative walkthrough definitions.++Walkthroughs are intentionally data-only. They may point at routes and stable+``data-walkthrough`` targets, listen for named UI signals, or use a host-owned+status check. They may never embed JavaScript, selectors outside the+walkthrough namespace, commands, or arbitrary API requests.+"""++import json+import re+from copy import deepcopy+from typing import Any, Dict, List++from app import db+from app.models.system_settings import SystemSettings+++MAX_WALKTHROUGHS = 32+MAX_STEPS = 32+MAX_DOCUMENT_BYTES = 128 * 1024+COMPLETION_TYPES = frozenset({'manual', 'route', 'signal', 'check', 'target'})++_CUSTOM_KEY = 'walkthroughs.custom.definitions'+_ID_RE = re.compile(r'^[a-z0-9][a-z0-9._-]{0,79}$')+_TOKEN_RE = re.compile(r'^[a-z0-9][a-z0-9._:-]{0,119}$')+_TARGET_RE = re.compile(r'^[a-z0-9][a-z0-9._:-]{0,79}$')+_LEVELS = {'read', 'write', 'admin'}+_GUIDE_FIELDS = {+ '$schema', 'id', 'title', 'title_key', 'description', 'description_key',+ 'duration', 'duration_key', 'icon', 'tone', 'secondary', 'permissions', 'steps',+}+_STEP_FIELDS = {+ 'id', 'title', 'title_key', 'description', 'description_key', 'action',+ 'action_key', 'path', 'target', 'completion',+}+_COMPLETION_FIELDS = {'type', 'path', 'signal', 'check'}+++class WalkthroughDefinitionError(ValueError):+ """Raised when a declarative walkthrough document is invalid."""+++def _bounded_string(value: Any, *, maximum: int) -> bool:+ return isinstance(value, str) and 0 < len(value.strip()) <= maximum+++def validate_walkthrough_definitions(raw: Any, *, field: str = 'walkthroughs') -> List[str]:+ """Return precise validation problems for a walkthrough definition list."""+ if not isinstance(raw, list):+ return [f'{field} must be a list']+ if len(raw) > MAX_WALKTHROUGHS:+ return [f'{field} may contain at most {MAX_WALKTHROUGHS} walkthroughs']++ problems = []+ seen_guides = set()+ for guide_index, guide in enumerate(raw):+ base = f'{field}[{guide_index}]'+ if not isinstance(guide, dict):+ problems.append(f'{base} must be an object')+ continue++ unknown_guide_fields = sorted(set(guide) - _GUIDE_FIELDS)+ if unknown_guide_fields:+ problems.append(f'{base} contains unsupported fields: {", ".join(unknown_guide_fields)}')++ guide_id = guide.get('id')+ if not isinstance(guide_id, str) or not _ID_RE.fullmatch(guide_id):+ problems.append(f'{base}.id must match {_ID_RE.pattern}')+ elif guide_id in seen_guides:+ problems.append(f'{base}.id duplicates {guide_id!r}')+ else:+ seen_guides.add(guide_id)++ for name, maximum in (+ ('title', 120), ('description', 320), ('duration', 80)):+ if name in guide and not _bounded_string(guide[name], maximum=maximum):+ problems.append(f'{base}.{name} must be a non-empty string up to {maximum} characters')+ if not _bounded_string(guide.get('title'), maximum=120):+ problems.append(f'{base}.title is required')+ if not _bounded_string(guide.get('description'), maximum=320):+ problems.append(f'{base}.description is required')++ for name in ('title_key', 'description_key', 'duration_key', 'icon', 'tone'):+ if name in guide and not _bounded_string(guide[name], maximum=120):+ problems.append(f'{base}.{name} must be a non-empty string up to 120 characters')+ if 'secondary' in guide and not isinstance(guide['secondary'], bool):+ problems.append(f'{base}.secondary must be a boolean')++ permissions = guide.get('permissions', [])+ if not isinstance(permissions, list) or len(permissions) > 16:+ problems.append(f'{base}.permissions must be a list with at most 16 entries')+ else:+ for permission_index, permission in enumerate(permissions):+ pbase = f'{base}.permissions[{permission_index}]'+ if not isinstance(permission, dict):+ problems.append(f'{pbase} must be an object')+ continue+ if not _bounded_string(permission.get('feature'), maximum=80):+ problems.append(f'{pbase}.feature is required')+ if permission.get('level') not in _LEVELS:+ problems.append(f'{pbase}.level must be read, write, or admin')++ steps = guide.get('steps')+ if not isinstance(steps, list) or not steps:+ problems.append(f'{base}.steps must be a non-empty list')+ continue+ if len(steps) > MAX_STEPS:+ problems.append(f'{base}.steps may contain at most {MAX_STEPS} steps')+ continue++ seen_steps = set()+ for step_index, step in enumerate(steps):+ sbase = f'{base}.steps[{step_index}]'+ if not isinstance(step, dict):+ problems.append(f'{sbase} must be an object')+ continue+ unknown_step_fields = sorted(set(step) - _STEP_FIELDS)+ if unknown_step_fields:+ problems.append(f'{sbase} contains unsupported fields: {", ".join(unknown_step_fields)}')+ step_id = step.get('id')+ if not isinstance(step_id, str) or not _ID_RE.fullmatch(step_id):+ problems.append(f'{sbase}.id must match {_ID_RE.pattern}')+ elif step_id in seen_steps:+ problems.append(f'{sbase}.id duplicates {step_id!r}')+ else:+ seen_steps.add(step_id)++ if not _bounded_string(step.get('title'), maximum=120):+ problems.append(f'{sbase}.title is required')+ if not _bounded_string(step.get('description'), maximum=500):+ problems.append(f'{sbase}.description is required')+ for name, maximum in (+ ('action', 80), ('title_key', 120),+ ('description_key', 120), ('action_key', 120)):+ if name in step and not _bounded_string(step[name], maximum=maximum):+ problems.append(f'{sbase}.{name} must be a non-empty string up to {maximum} characters')++ path = step.get('path')+ if path is not None and (not _bounded_string(path, maximum=500) or not path.startswith('/')):+ problems.append(f'{sbase}.path must begin with / and contain at most 500 characters')+ target = step.get('target')+ if target is not None and (not isinstance(target, str) or not _TARGET_RE.fullmatch(target)):+ problems.append(f'{sbase}.target must be a stable data-walkthrough token')++ completion = step.get('completion', {'type': 'manual'})+ if not isinstance(completion, dict):+ problems.append(f'{sbase}.completion must be an object')+ continue+ unknown_completion_fields = sorted(set(completion) - _COMPLETION_FIELDS)+ if unknown_completion_fields:+ problems.append(+ f'{sbase}.completion contains unsupported fields: '+ f'{", ".join(unknown_completion_fields)}')+ completion_type = completion.get('type', 'manual')+ if completion_type not in COMPLETION_TYPES:+ problems.append(+ f'{sbase}.completion.type must be one of {", ".join(sorted(COMPLETION_TYPES))}')+ elif completion_type == 'route':+ route = completion.get('path') or path+ if not isinstance(route, str) or not route.startswith('/') or len(route) > 500:+ problems.append(f'{sbase}.completion.path must be a route beginning with /')+ elif completion_type == 'signal':+ signal = completion.get('signal')+ if not isinstance(signal, str) or not _TOKEN_RE.fullmatch(signal):+ problems.append(f'{sbase}.completion.signal must be a stable event token')+ elif completion_type == 'check':+ check = completion.get('check')+ if not isinstance(check, str) or not _TOKEN_RE.fullmatch(check):+ problems.append(f'{sbase}.completion.check must be a named host check')+ elif completion_type == 'target' and target is None:+ problems.append(f'{sbase}.completion target requires step.target')++ try:+ encoded_size = len(json.dumps(raw, ensure_ascii=False).encode('utf-8'))+ if encoded_size > MAX_DOCUMENT_BYTES:+ problems.append(f'{field} exceeds the {MAX_DOCUMENT_BYTES}-byte limit')+ except (TypeError, ValueError):+ problems.append(f'{field} must contain JSON-compatible values')++ return problems+++class WalkthroughDefinitionService:+ """Panel-wide custom walkthrough library managed by administrators."""++ @staticmethod+ def get_definitions() -> List[Dict[str, Any]]:+ raw = SystemSettings.get(_CUSTOM_KEY, [])+ if validate_walkthrough_definitions(raw, field='definitions'):+ return []+ return deepcopy(raw)++ @staticmethod+ def save_definitions(raw: Any) -> List[Dict[str, Any]]:+ problems = validate_walkthrough_definitions(raw, field='definitions')+ if problems:+ raise WalkthroughDefinitionError('; '.join(problems))+ definitions = deepcopy(raw)+ SystemSettings.set(+ key=_CUSTOM_KEY,+ value=definitions,+ value_type='json',+ description='Panel-wide custom guided walkthrough definitions',+ )+ db.session.commit()+ return definitionsdiff --git a/backend/app/utils/sdk.py b/backend/app/utils/sdk.pyindex de402065..21d065cf 100644--- a/backend/app/utils/sdk.py+++ b/backend/app/utils/sdk.py@@ -31,6 +31,7 @@ from app.utils.version import compare_versions# Keep in lock-step with frontend/src/plugins/sdk/index.js `SDK_VERSION`.#+# 1.5.0 — declarative walkthrough authoring helpers and useWalkthroughs.# 1.3.0 — plan 79: localization. useTranslation/Trans/t, useLocale, useLabel,# and the locale-aware format door (useFormat + formatDate/Number/Relative/…).# i18next and react-i18next also became SHARED vendor singletons, so an@@ -40,7 +41,7 @@ from app.utils.version import compare_versions# 1.2.0 — plan 52 Phases 4-5: layout/feedback primitives, ui/* form kit,# common hooks, format utils, and the cross-feature embeds (git repo-connect,# backups ProtectionPanel) the WordPress runtime-ESM extraction needed.-SDK_VERSION = '1.4.0'+SDK_VERSION = '1.5.0'def _version_tuple(v):diff --git a/backend/tests/test_plugins_pipeline.py b/backend/tests/test_plugins_pipeline.pyindex 634eecc0..f0beb697 100644--- a/backend/tests/test_plugins_pipeline.py+++ b/backend/tests/test_plugins_pipeline.py@@ -72,6 +72,19 @@ def _write_builtin(builtin_dir, slug='serverkit-demo', version='1.0.0','component': 'DemoWidget', 'category': 'Utility','w': 3, 'h': 2, 'min': [2, 2],'default_cfg': {'limit': 5}}],+ 'walkthroughs': [{+ 'id': 'demo-first-run',+ 'title': 'Try Demo',+ 'description': 'Open Demo and complete one safe action.',+ 'steps': [{+ 'id': 'open-demo',+ 'title': 'Open Demo',+ 'description': 'Navigate to the Demo extension.',+ 'path': '/demo',+ 'target': 'demo-page',+ 'completion': {'type': 'route', 'path': '/demo'},+ }],+ }],},}(folder / 'plugin.json').write_text(json.dumps(manifest), encoding='utf-8')@@ -219,7 +232,7 @@ def test_contributions_endpoint_envelope(app, client, auth_headers, plugin_dirs)# The envelope always carries every key.for key in ('nav', 'routes', 'page_titles', 'command_palette', 'widgets',- 'dashboard_widgets', 'layouts', 'tabs', 'ai'):+ 'dashboard_widgets', 'layouts', 'tabs', 'walkthroughs', 'ai'):assert key in data# Contributions are tagged with the source plugin slug.@@ -243,6 +256,10 @@ def test_contributions_endpoint_envelope(app, client, auth_headers, plugin_dirs)for w in data['dashboard_widgets'])assert not any(w.get('id') == 'demo-widget' for w in data['widgets'])+ assert any(w.get('plugin') == 'serverkit-demo'+ and w.get('id') == 'demo-first-run'+ for w in data['walkthroughs'])+def test_disabled_plugin_drops_from_contributions(app, client, auth_headers, plugin_dirs):_write_builtin(plugin_dirs['builtin'])@@ -356,6 +373,21 @@ def test_manifest_lint_rejects_bad_shapes():'contributions': {'routes': [{'path': 'x'}]}})with pytest.raises(ValueError, match='lifecycle.install'):_validate_manifest({**_LINT_BASE, 'lifecycle': {'install': 'no-colon'}})+ with pytest.raises(ValueError, match=r'walkthroughs\[0\].steps\[0\].target'):+ _validate_manifest({+ **_LINT_BASE,+ 'contributions': {'walkthroughs': [{+ 'id': 'bad-guide',+ 'title': 'Bad Guide',+ 'description': 'Uses an arbitrary selector.',+ 'steps': [{+ 'id': 'bad-step',+ 'title': 'Bad Step',+ 'description': 'This must fail.',+ 'target': '#password',+ }],+ }]},+ })def test_manifest_lint_unknown_contrib_kind_warns_not_fails():diff --git a/backend/tests/test_walkthroughs.py b/backend/tests/test_walkthroughs.pyindex b617b730..d54c62de 100644--- a/backend/tests/test_walkthroughs.py+++ b/backend/tests/test_walkthroughs.py@@ -53,3 +53,76 @@ def test_walkthrough_state_rejects_unbounded_or_unknown_data(client, db_session)def test_walkthrough_state_requires_authentication(client):assert client.get('/api/v1/walkthroughs/state').status_code in (401, 422)assert client.put('/api/v1/walkthroughs/state', json={}).status_code in (401, 422)+++def _definition(guide_id='custom-guide'):+ return {+ 'id': guide_id,+ 'title': 'Custom guide',+ 'description': 'Complete a safe, declarative task.',+ 'duration': 'About 3 minutes',+ 'secondary': True,+ 'permissions': [{'feature': 'applications', 'level': 'write'}],+ 'steps': [{+ 'id': 'open-services',+ 'title': 'Open services',+ 'description': 'Navigate to the services list.',+ 'action': 'Open services',+ 'path': '/services',+ 'target': 'services-list',+ 'completion': {'type': 'route', 'path': '/services'},+ }],+ }+++def test_admin_can_publish_panel_walkthroughs_visible_to_viewers(client, db_session):+ admin = make_user(db_session, role='admin', username='guide-admin')+ viewer = make_user(db_session, role='viewer', username='guide-reader')++ response = client.put(+ '/api/v1/walkthroughs/definitions',+ headers=headers_for(admin),+ json={'definitions': [_definition()]},+ )+ assert response.status_code == 200+ assert response.get_json()['definitions'][0]['id'] == 'custom-guide'++ response = client.get(+ '/api/v1/walkthroughs/definitions',+ headers=headers_for(viewer),+ )+ assert response.status_code == 200+ assert response.get_json()['definitions'][0]['title'] == 'Custom guide'+++def test_viewer_cannot_publish_walkthrough_definitions(client, db_session):+ viewer = make_user(db_session, role='viewer', username='guide-publisher')+ response = client.put(+ '/api/v1/walkthroughs/definitions',+ headers=headers_for(viewer),+ json={'definitions': [_definition()]},+ )+ assert response.status_code == 403+++def test_walkthrough_definition_rejects_executable_or_arbitrary_targets(client, db_session):+ admin = make_user(db_session, role='admin', username='guide-validator')+ definition = _definition()+ definition['steps'][0]['target'] = '#password-field'+ definition['steps'][0]['javascript'] = 'alert(1)'++ response = client.put(+ '/api/v1/walkthroughs/definitions',+ headers=headers_for(admin),+ json={'definitions': [definition]},+ )+ assert response.status_code == 400+ assert 'data-walkthrough token' in response.get_json()['error']+++def test_walkthrough_definitions_require_authentication(client):+ assert client.get('/api/v1/walkthroughs/definitions').status_code in (401, 422)+ assert client.put(+ '/api/v1/walkthroughs/definitions',+ json={'definitions': [_definition()]},+ ).status_code in (401, 422)diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.mdindex 1eb18c0c..bcdb957b 100644--- a/docs/EXTENSIONS.md+++ b/docs/EXTENSIONS.md@@ -604,6 +604,74 @@ call `i18next.init()` or `changeLanguage()` from an extension: the panel ownsboth, and calling them would reconfigure or switch the language for the wholepanel.+## Guided walkthrough contributions++Extensions can add safe, declarative guides to the panel's Walkthroughs dock.+The panel namespaces every contributed id with the extension slug, filters the+guide through the declared RBAC requirements, and removes it immediately when+the extension is disabled. No extension JavaScript is needed for route,+manual, or target-visible steps:++```jsonc+"contributions": {+ "walkthroughs": [{+ "id": "first-site",+ "title": "Launch your first site",+ "description": "Create the site and verify that it is online.",+ "duration": "About 5 minutes",+ "icon": "globe",+ "tone": "green",+ "secondary": true,+ "permissions": [{ "feature": "applications", "level": "write" }],+ "steps": [{+ "id": "open-create",+ "title": "Open the create flow",+ "description": "Start from the extension's site list.",+ "action": "Create site",+ "path": "/my-extension/new",+ "target": "myext-create-site",+ "completion": { "type": "route", "path": "/my-extension/new" }+ }, {+ "id": "launch-site",+ "title": "Launch the site",+ "description": "Submit the reviewed configuration.",+ "target": "myext-submit-site",+ "completion": { "type": "signal", "signal": "myext.site-created" }+ }]+ }]+}+```++`target` is the value of a stable `data-walkthrough` attribute, never a CSS+selector. For the example above, the extension renders+`data-walkthrough="myext-submit-site"`. This restriction prevents a guide from+reaching into password fields or depending on fragile generated class names.++Five completion modes are supported:++| Type | Completes when |+|---|---|+| `manual` | The operator chooses **Done · next step**. |+| `route` | The current path matches `completion.path` (or the step's `path`). |+| `signal` | The UI emits the named signal after a successful operation. |+| `check` | A host-owned, allowlisted status check returns success. |+| `target` | The stable `data-walkthrough` target becomes visible. |++Emit success signals through the SDK only after the operation succeeds:++```js+import { emitWalkthroughSignal } from 'serverkit-sdk';++await createSite(values);+emitWalkthroughSignal('myext.site-created', { siteId });+```++Definitions cannot contain JavaScript, commands, arbitrary API calls, or raw+selectors. The same validator runs during extension install and when an admin+publishes a custom guide from Walkthrough Studio. The editor schema lives at+`docs/schemas/walkthrough.schema.json`; TypeScript definitions live at+`frontend/src/plugins/sdk/walkthroughs.d.ts`.+### Checking your own extensionThe panel's censuses take a `--root`, so run them against your repo instead of@@ -678,6 +746,7 @@ readable *"needs panel SDK ^1.3.0 (this panel offers 1.2.0)"* at install time.| SDK | Added ||---|---|+| `^1.5.0` | Declarative walkthrough authoring: manifest contributions, validation/normalization helpers, success-signal emission, and the walkthrough runtime hook. || `^1.3.0` | Localization: `useTranslation`, `Trans`, `t`, `useLocale`, `useLabel`, `useFormat` and the `formatDate`/`formatNumber`/`formatRelative` door. `i18next` and `react-i18next` became shared singletons, so an extension that **externalizes** them needs this SDK or newer. || `^1.2.0` | Layout/feedback primitives, the `ui/*` form kit, common hooks, format utils, and the cross-feature embeds (git repo-connect, backups `ProtectionPanel`). |diff --git a/docs/schemas/walkthrough.schema.json b/docs/schemas/walkthrough.schema.jsonnew file mode 100644index 00000000..91d8d56e--- /dev/null+++ b/docs/schemas/walkthrough.schema.json@@ -0,0 +1,116 @@+{+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://serverkit.ai/schemas/walkthrough.schema.json",+ "title": "ServerKit Walkthrough",+ "description": "A safe, declarative guided flow contributed by an extension or created in Walkthrough Studio.",+ "type": "object",+ "additionalProperties": false,+ "required": ["id", "title", "description", "steps"],+ "properties": {+ "$schema": { "type": "string" },+ "id": { "$ref": "#/$defs/id" },+ "title": { "type": "string", "minLength": 1, "maxLength": 120 },+ "title_key": { "type": "string", "minLength": 1, "maxLength": 120 },+ "description": { "type": "string", "minLength": 1, "maxLength": 320 },+ "description_key": { "type": "string", "minLength": 1, "maxLength": 120 },+ "duration": { "type": "string", "minLength": 1, "maxLength": 80 },+ "duration_key": { "type": "string", "minLength": 1, "maxLength": 120 },+ "icon": { "type": "string", "minLength": 1, "maxLength": 120 },+ "tone": { "type": "string", "minLength": 1, "maxLength": 120 },+ "secondary": { "type": "boolean", "default": true },+ "permissions": {+ "type": "array",+ "maxItems": 16,+ "items": {+ "type": "object",+ "additionalProperties": false,+ "required": ["feature", "level"],+ "properties": {+ "feature": { "type": "string", "minLength": 1, "maxLength": 80 },+ "level": { "enum": ["read", "write", "admin"] }+ }+ }+ },+ "steps": {+ "type": "array",+ "minItems": 1,+ "maxItems": 32,+ "items": { "$ref": "#/$defs/step" }+ }+ },+ "$defs": {+ "id": {+ "type": "string",+ "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$"+ },+ "target": {+ "type": "string",+ "description": "The value of a data-walkthrough attribute. CSS selectors are not accepted.",+ "pattern": "^[a-z0-9][a-z0-9._:-]{0,79}$"+ },+ "token": {+ "type": "string",+ "pattern": "^[a-z0-9][a-z0-9._:-]{0,119}$"+ },+ "completion": {+ "oneOf": [+ {+ "type": "object",+ "additionalProperties": false,+ "required": ["type"],+ "properties": { "type": { "const": "manual" } }+ },+ {+ "type": "object",+ "additionalProperties": false,+ "required": ["type"],+ "properties": {+ "type": { "const": "route" },+ "path": { "type": "string", "pattern": "^/", "maxLength": 500 }+ }+ },+ {+ "type": "object",+ "additionalProperties": false,+ "required": ["type", "signal"],+ "properties": {+ "type": { "const": "signal" },+ "signal": { "$ref": "#/$defs/token" }+ }+ },+ {+ "type": "object",+ "additionalProperties": false,+ "required": ["type", "check"],+ "properties": {+ "type": { "const": "check" },+ "check": { "$ref": "#/$defs/token" }+ }+ },+ {+ "type": "object",+ "additionalProperties": false,+ "required": ["type"],+ "properties": { "type": { "const": "target" } }+ }+ ]+ },+ "step": {+ "type": "object",+ "additionalProperties": false,+ "required": ["id", "title", "description"],+ "properties": {+ "id": { "$ref": "#/$defs/id" },+ "title": { "type": "string", "minLength": 1, "maxLength": 120 },+ "title_key": { "type": "string", "minLength": 1, "maxLength": 120 },+ "description": { "type": "string", "minLength": 1, "maxLength": 500 },+ "description_key": { "type": "string", "minLength": 1, "maxLength": 120 },+ "action": { "type": "string", "minLength": 1, "maxLength": 80 },+ "action_key": { "type": "string", "minLength": 1, "maxLength": 120 },+ "path": { "type": "string", "pattern": "^/", "maxLength": 500 },+ "target": { "$ref": "#/$defs/target" },+ "completion": { "$ref": "#/$defs/completion" }+ }+ }+ }+}diff --git a/scripts/new-extension.mjs b/scripts/new-extension.mjsindex cd57fdb5..64767d48 100644--- a/scripts/new-extension.mjs+++ b/scripts/new-extension.mjs@@ -25,6 +25,7 @@import { promises as fs } from 'fs';import path from 'path';import { fileURLToPath } from 'url';+import { validateWalkthroughDefinition } from '../frontend/src/services/walkthroughRegistry.js';const __dirname = path.dirname(fileURLToPath(import.meta.url));const ROOT = path.resolve(__dirname, '..');@@ -43,6 +44,7 @@ const REQUIRED_CONTRIB_KEYS = {command_palette: ['label', 'path'],widgets: ['slot', 'component'],layouts: ['id', 'component'],+ walkthroughs: ['id', 'title', 'description', 'steps'],};const KNOWN_CONTRIB_KINDS = new Set([...Object.keys(REQUIRED_CONTRIB_KEYS), 'page_titles', 'ai']);@@ -133,6 +135,14 @@ function validateManifest(manifest) {&& (typeof contrib.page_titles !== 'object' || Array.isArray(contrib.page_titles))) {problems.push('contributions.page_titles must be an object of path -> title');}+ if (Array.isArray(contrib.walkthroughs)) {+ contrib.walkthroughs.forEach((walkthrough, i) => {+ for (const item of validateWalkthroughDefinition(walkthrough)) {+ const suffix = item.path ? `.${item.path}` : '';+ problems.push(`contributions.walkthroughs[${i}]${suffix}: ${item.message}`);+ }+ });+ }}return { problems, warnings };