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
fix(walkthroughs): accept the step-level shorthand in extension manifests
Juan Denis332ad73770e1
diff --git a/backend/app/services/walkthrough_definition_service.py b/backend/app/services/walkthrough_definition_service.pyindex bbb15878..ea247e2d 100644--- a/backend/app/services/walkthrough_definition_service.py+++ b/backend/app/services/walkthrough_definition_service.py@@ -32,6 +32,9 @@ _GUIDE_FIELDS = {_STEP_FIELDS = {'id', 'title', 'title_key', 'description', 'description_key', 'action','action_key', 'path', 'target', 'completion',+ # Step-level shorthand for the common single-condition cases. Core+ # walkthroughs are authored this way, so extensions may be too.+ 'route', 'signal', 'check',}_COMPLETION_FIELDS = {'type', 'path', 'signal', 'check'}@@ -44,6 +47,32 @@ def _bounded_string(value: Any, *, maximum: int) -> bool:return isinstance(value, str) and 0 < len(value.strip()) <= maximum+def _completion_for(step: Dict[str, Any]):+ """Resolve a step's completion and say which spelling supplied it.++ An explicit ``completion`` block always wins; otherwise a step may carry+ ``signal``, ``check`` or ``route`` directly. Returns ``(completion,+ shorthand_field)`` where ``shorthand_field`` is None for an explicit+ block, so problems can be reported against the key the author actually+ wrote. Kept in lock-step with ``completionFor()`` in+ frontend/src/services/walkthroughRegistry.js.+ """+ if 'completion' in step:+ return step['completion'], None+ if step.get('signal'):+ return {'type': 'signal', 'signal': step['signal']}, 'signal'+ if step.get('check'):+ return {'type': 'check', 'check': step['check']}, 'check'+ if step.get('route'):+ return {'type': 'route', 'path': step['route']}, 'route'+ return {'type': 'manual'}, None+++def _cfield(cbase, shorthand, name):+ """Path to a completion sub-field, collapsed when shorthand supplied it."""+ return cbase if shorthand else f'{cbase}.{name}'++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):@@ -142,33 +171,37 @@ def validate_walkthrough_definitions(raw: Any, *, field: str = 'walkthroughs') -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'})+ completion, shorthand = _completion_for(step)+ cbase = f'{sbase}.{shorthand}' if shorthand else f'{sbase}.completion'if not isinstance(completion, dict):- problems.append(f'{sbase}.completion must be an object')+ problems.append(f'{cbase} must be an object')continueunknown_completion_fields = sorted(set(completion) - _COMPLETION_FIELDS)if unknown_completion_fields:problems.append(- f'{sbase}.completion contains unsupported fields: '+ f'{cbase} 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))}')+ f'{cbase}.type must be one of {", ".join(sorted(COMPLETION_TYPES))}')elif completion_type == 'route':route = completion.get('path') or pathif not isinstance(route, str) or not route.startswith('/') or len(route) > 500:- problems.append(f'{sbase}.completion.path must be a route beginning with /')+ problems.append(+ f'{_cfield(cbase, shorthand, "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')+ problems.append(+ f'{_cfield(cbase, shorthand, "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')+ problems.append(+ f'{_cfield(cbase, shorthand, "check")} must be a named host check')elif completion_type == 'target' and target is None:- problems.append(f'{sbase}.completion target requires step.target')+ problems.append(f'{cbase} target requires step.target')try:encoded_size = len(json.dumps(raw, ensure_ascii=False).encode('utf-8'))diff --git a/backend/tests/test_walkthroughs.py b/backend/tests/test_walkthroughs.pyindex d54c62de..d594e01c 100644--- a/backend/tests/test_walkthroughs.py+++ b/backend/tests/test_walkthroughs.py@@ -126,3 +126,47 @@ def test_walkthrough_definitions_require_authentication(client):'/api/v1/walkthroughs/definitions',json={'definitions': [_definition()]},).status_code in (401, 422)+++def test_walkthrough_definition_accepts_step_level_shorthand(client, db_session):+ """`signal:` on a step is shorthand for a signal completion block.++ Core walkthroughs are authored that way, so a manifest that copies the+ pattern must install rather than be rejected at the door.+ """+ admin = make_user(db_session, role='admin', username='guide-shorthand')+ definition = _definition()+ step = definition['steps'][0]+ del step['completion']+ step['signal'] = 'service-created'++ 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]['steps'][0]['signal'] == 'service-created'+++def test_walkthrough_shorthand_is_held_to_the_same_token_rules(client, db_session):+ """The shorthand is a spelling, not an escape hatch.++ An invalid token is still rejected, and the problem names the key the+ author actually wrote rather than the completion block it desugars to.+ """+ admin = make_user(db_session, role='admin', username='guide-shorthand-bad')+ definition = _definition()+ step = definition['steps'][0]+ del step['completion']+ step['signal'] = 'Not A Token!'++ response = client.put(+ '/api/v1/walkthroughs/definitions',+ headers=headers_for(admin),+ json={'definitions': [definition]},+ )+ assert response.status_code == 400+ error = response.get_json()['error']+ assert '.signal' in error+ assert '.completion.signal' not in errordiff --git a/docs/schemas/walkthrough.schema.json b/docs/schemas/walkthrough.schema.jsonindex 91d8d56e..e2d022c6 100644--- a/docs/schemas/walkthrough.schema.json+++ b/docs/schemas/walkthrough.schema.json@@ -109,8 +109,13 @@"action_key": { "type": "string", "minLength": 1, "maxLength": 120 },"path": { "type": "string", "pattern": "^/", "maxLength": 500 },"target": { "$ref": "#/$defs/target" },- "completion": { "$ref": "#/$defs/completion" }- }+ "completion": { "$ref": "#/$defs/completion" },+ "route": { "type": "string", "pattern": "^/", "maxLength": 500 },+ "signal": { "$ref": "#/$defs/token" },+ "check": { "$ref": "#/$defs/token" }+ },+ "description": "route, signal and check are shorthand for the matching single-condition completion block. An explicit completion always wins."+}}}