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.

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.py
index 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')
continue
unknown_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 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 /')
+ 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.py
index 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 error
diff --git a/docs/schemas/walkthrough.schema.json b/docs/schemas/walkthrough.schema.json
index 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."
+
}
}
}