stackport 0.4.1__tar.gz → 0.4.3__tar.gz

stackport-0.4.3/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include ui/dist *
+recursive-include backend/learn/trails *.json

{stackport-0.4.1/stackport.egg-info → stackport-0.4.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: stackport
-Version: 0.4.1
+Version: 0.4.3
 Summary: Universal AWS resource browser for local emulators
 Author: Davi Reis Vieira
 License: MIT
 Project-URL: Homepage, https://github.com/DaviReisVieira/stackport
 Project-URL: Repository, https://github.com/DaviReisVieira/stackport
 Project-URL: Issues, https://github.com/DaviReisVieira/stackport/issues
-Keywords: aws,ministack,localstack,browser,devtools,emulator
+Keywords: aws,ministack,floci,localstack,browser,devtools,emulator
 Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: FastAPI
 Classifier: Intended Audience :: Developers
@@ -70,19 +70,23 @@ Dynamic: license-file
 - **Write operations** — upload/delete S3 objects, query DynamoDB, invoke Lambda, send/receive SQS messages
 - **Real AWS support** — connect to real AWS accounts with read-only mode by default
 - **Per-endpoint authentication** — default credentials, AWS profiles (SSO/AssumeRole), or static keys per endpoint
+- **Guided lessons** — hands-on AWS tutorials that run inside the console and verify your real resource state
 - **Tag management** — unified tagging across 21 resource types
 - **CLI** — `stackport status`, `list`, `describe`, `export` with JSON/CSV/table output
 - **Real-time dashboard** with WebSocket-powered live updates
 - **Keyboard shortcuts** — 16 shortcuts for fast navigation (press `?` to view)
-- Single Docker image, works with MiniStack, LocalStack, Moto, or any AWS-compatible endpoint
+- Single Docker image, works with [MiniStack](https://github.com/ministackorg/ministack), [Floci](https://github.com/floci-io/floci), LocalStack, Moto, or any AWS-compatible endpoint
 
 ## Quick Start
 
-### With a local emulator (recommended)
+### With a local emulator
+
+Start whichever emulator you use, then point StackPort at it:
 
 ```bash
-# Start MiniStack (or LocalStack, Moto, etc.)
-pip install ministack && ministack
+# Start an emulator on :4566 (pick one)
+docker run -d -p 4566:4566 ministackorg/ministack   # MiniStack
+docker run -d -p 4566:4566 floci/floci              # Floci
 
 # Start StackPort
 pip install stackport
@@ -107,16 +111,32 @@ You can also configure per-endpoint authentication from the Settings UI — sele
 
 When connected to real AWS, StackPort shows a warning banner and operates in read-only mode unless writes are explicitly enabled.
 
-### Docker Compose (MiniStack + StackPort)
+### Docker Compose
+
+Each example runs the emulator, StackPort, and a one-shot `seed` container that creates a few resources (S3, SQS, SNS, DynamoDB, Secrets Manager, IAM, Logs, Step Functions) so the dashboard has something to show on first load. Both use the same seed. Swap in LocalStack, Moto, or any AWS-compatible endpoint by replacing the emulator service and updating `AWS_ENDPOINT_URL`.
 
-This example uses [MiniStack](https://github.com/Nahuel990/ministack) as the emulator, but you can swap it for LocalStack, Moto, or any AWS-compatible endpoint — just update `AWS_ENDPOINT_URL`.
+**MiniStack + StackPort** — [`examples/docker-compose.yml`](examples/docker-compose.yml)
 
 ```bash
 curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/examples/docker-compose.yml
 docker compose up -d
 # Open http://localhost:8080
+# If the dashboard is empty: docker compose logs seed
 ```
 
+[MiniStack](https://github.com/ministackorg/ministack) derives the URLs it returns (SQS queue URLs, pre-signed URLs) from the request `Host`, so they resolve from other containers and from the host without extra configuration.
+
+**Floci + StackPort** — [`examples/docker-compose.floci.yml`](examples/docker-compose.floci.yml)
+
+```bash
+curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/examples/docker-compose.floci.yml
+docker compose -f docker-compose.floci.yml up -d
+# Open http://localhost:8080
+# If the dashboard is empty: docker compose -f docker-compose.floci.yml logs seed
+```
+
+[Floci](https://github.com/floci-io/floci) takes the hostname for the URLs it returns from `FLOCI_HOSTNAME`, which the example sets to `floci` so they resolve from other containers. From the host, reach the same resources through `http://localhost:4566`.
+
 ### Docker (standalone)
 
 ```bash
@@ -206,6 +226,21 @@ You can test connections before saving using the "Test Connection" button in the
 
 All other services use a searchable resource table with JSON detail view, pagination, and export (JSON/CSV).
 
+## Learn
+
+Guided lessons that run inside StackPort itself, against your own emulator. A panel walks you through a lesson step by step while hotspots point at the actual controls, and StackPort checks the live resource state, so a step only turns green when the thing genuinely exists.
+
+Open **Learn** in the sidebar (or press `g l`) and start a lesson. Every step gives you two ways through it:
+
+- **Do it here** — the popover points at the control to use, with the exact values to type, copyable.
+- **With the CLI** — the command, already filled in with your endpoint and your resource names, plus an explanation of what each flag does.
+
+Either way, verification is the same: StackPort calls the real API and reports what it found. Do the work in a terminal and the step turns green on its own within a few seconds, no clicking required. Nothing is a gate, either: any step can be skipped and re-checked later.
+
+You pick the names. A lesson generates something like `stackport-learn-k3xz` and every command and field on screen uses it, so the commands can be copied and run without editing. Change it under "Names used in this lesson" and everything follows.
+
+Lessons only run against a local emulator, since they create and delete resources. Progress is stored locally in `~/.stackport/learn_progress.json`. Set `STACKPORT_LEARN=false` to remove Learn entirely.
+
 ## Tag Management
 
 Unified tag read/write across 21 resource types:
@@ -244,6 +279,7 @@ Press `?` anywhere to see all shortcuts.
 | `b` | Toggle sidebar |
 | `g d` | Go to Dashboard |
 | `g r` | Go to Resources |
+| `g l` | Go to Learn |
 | `/` | Focus search |
 | `j` / `k` | Navigate up/down in resource list |
 | `[` / `]` | Previous/next service |
@@ -263,12 +299,13 @@ Press `?` anywhere to see all shortcuts.
 | `STACKPORT_PORT` | `8080` | StackPort server port |
 | `STACKPORT_ALLOW_WRITES` | `true` | Enable write operations (POST/PUT/DELETE) |
 | `STACKPORT_S3_MAX_UPLOAD_MB` | `100` | Max S3 upload size per object (MiB) |
+| `STACKPORT_LEARN` | `true` | Guided tutorials. `false` removes the Learn routes and UI |
 | `STACKPORT_SERVICES` | *(35 services)* | Comma-separated list of services to probe |
 | `STACKPORT_PROBE_TIMEOUT` | `5` | Seconds before a service probe times out |
 | `STACKPORT_CACHE_TTL` | `5` | Seconds to cache service stats |
 | `STACKPORT_PROBE_WORKERS` | `10` | Max concurrent workers for service probing |
 | `STACKPORT_ENDPOINTS` | *(unset)* | Multiple endpoints: `local=http://localhost:4566,staging=http://...` |
-| `STACKPORT_DATA_DIR` | `~/.stackport` | Directory for persistent config (endpoints.json) |
+| `STACKPORT_DATA_DIR` | `~/.stackport` | Directory for persistent config (endpoints.json, learn_progress.json) |
 | `LOG_LEVEL` | `INFO` | Python log level (`DEBUG` shows healthcheck logs) |
 
 ## Supported Services (35)
@@ -333,6 +370,10 @@ ui/src/
   lib/             API client, types, service icons, utils
 ```
 
+## Origin
+
+StackPort started as a web UI pull request to [MiniStack](https://github.com/ministackorg/ministack) ([ministack#116](https://github.com/ministackorg/ministack/pull/116)). The MiniStack maintainers suggested it would be more useful as a standalone tool that talks to any emulator over the standard AWS API, and that is what it became. Thanks to [@Nahuel990](https://github.com/Nahuel990) and [@McDoit](https://github.com/McDoit) for pushing it in that direction.
+
 ## Contributors
 
 <a href="https://github.com/DaviReisVieira/stackport/graphs/contributors">

{stackport-0.4.1 → stackport-0.4.3}/README.md

@@ -34,19 +34,23 @@
 - **Write operations** — upload/delete S3 objects, query DynamoDB, invoke Lambda, send/receive SQS messages
 - **Real AWS support** — connect to real AWS accounts with read-only mode by default
 - **Per-endpoint authentication** — default credentials, AWS profiles (SSO/AssumeRole), or static keys per endpoint
+- **Guided lessons** — hands-on AWS tutorials that run inside the console and verify your real resource state
 - **Tag management** — unified tagging across 21 resource types
 - **CLI** — `stackport status`, `list`, `describe`, `export` with JSON/CSV/table output
 - **Real-time dashboard** with WebSocket-powered live updates
 - **Keyboard shortcuts** — 16 shortcuts for fast navigation (press `?` to view)
-- Single Docker image, works with MiniStack, LocalStack, Moto, or any AWS-compatible endpoint
+- Single Docker image, works with [MiniStack](https://github.com/ministackorg/ministack), [Floci](https://github.com/floci-io/floci), LocalStack, Moto, or any AWS-compatible endpoint
 
 ## Quick Start
 
-### With a local emulator (recommended)
+### With a local emulator
+
+Start whichever emulator you use, then point StackPort at it:
 
 ```bash
-# Start MiniStack (or LocalStack, Moto, etc.)
-pip install ministack && ministack
+# Start an emulator on :4566 (pick one)
+docker run -d -p 4566:4566 ministackorg/ministack   # MiniStack
+docker run -d -p 4566:4566 floci/floci              # Floci
 
 # Start StackPort
 pip install stackport
@@ -71,16 +75,32 @@ You can also configure per-endpoint authentication from the Settings UI — sele
 
 When connected to real AWS, StackPort shows a warning banner and operates in read-only mode unless writes are explicitly enabled.
 
-### Docker Compose (MiniStack + StackPort)
+### Docker Compose
+
+Each example runs the emulator, StackPort, and a one-shot `seed` container that creates a few resources (S3, SQS, SNS, DynamoDB, Secrets Manager, IAM, Logs, Step Functions) so the dashboard has something to show on first load. Both use the same seed. Swap in LocalStack, Moto, or any AWS-compatible endpoint by replacing the emulator service and updating `AWS_ENDPOINT_URL`.
 
-This example uses [MiniStack](https://github.com/Nahuel990/ministack) as the emulator, but you can swap it for LocalStack, Moto, or any AWS-compatible endpoint — just update `AWS_ENDPOINT_URL`.
+**MiniStack + StackPort** — [`examples/docker-compose.yml`](examples/docker-compose.yml)
 
 ```bash
 curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/examples/docker-compose.yml
 docker compose up -d
 # Open http://localhost:8080
+# If the dashboard is empty: docker compose logs seed
 ```
 
+[MiniStack](https://github.com/ministackorg/ministack) derives the URLs it returns (SQS queue URLs, pre-signed URLs) from the request `Host`, so they resolve from other containers and from the host without extra configuration.
+
+**Floci + StackPort** — [`examples/docker-compose.floci.yml`](examples/docker-compose.floci.yml)
+
+```bash
+curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/examples/docker-compose.floci.yml
+docker compose -f docker-compose.floci.yml up -d
+# Open http://localhost:8080
+# If the dashboard is empty: docker compose -f docker-compose.floci.yml logs seed
+```
+
+[Floci](https://github.com/floci-io/floci) takes the hostname for the URLs it returns from `FLOCI_HOSTNAME`, which the example sets to `floci` so they resolve from other containers. From the host, reach the same resources through `http://localhost:4566`.
+
 ### Docker (standalone)
 
 ```bash
@@ -170,6 +190,21 @@ You can test connections before saving using the "Test Connection" button in the
 
 All other services use a searchable resource table with JSON detail view, pagination, and export (JSON/CSV).
 
+## Learn
+
+Guided lessons that run inside StackPort itself, against your own emulator. A panel walks you through a lesson step by step while hotspots point at the actual controls, and StackPort checks the live resource state, so a step only turns green when the thing genuinely exists.
+
+Open **Learn** in the sidebar (or press `g l`) and start a lesson. Every step gives you two ways through it:
+
+- **Do it here** — the popover points at the control to use, with the exact values to type, copyable.
+- **With the CLI** — the command, already filled in with your endpoint and your resource names, plus an explanation of what each flag does.
+
+Either way, verification is the same: StackPort calls the real API and reports what it found. Do the work in a terminal and the step turns green on its own within a few seconds, no clicking required. Nothing is a gate, either: any step can be skipped and re-checked later.
+
+You pick the names. A lesson generates something like `stackport-learn-k3xz` and every command and field on screen uses it, so the commands can be copied and run without editing. Change it under "Names used in this lesson" and everything follows.
+
+Lessons only run against a local emulator, since they create and delete resources. Progress is stored locally in `~/.stackport/learn_progress.json`. Set `STACKPORT_LEARN=false` to remove Learn entirely.
+
 ## Tag Management
 
 Unified tag read/write across 21 resource types:
@@ -208,6 +243,7 @@ Press `?` anywhere to see all shortcuts.
 | `b` | Toggle sidebar |
 | `g d` | Go to Dashboard |
 | `g r` | Go to Resources |
+| `g l` | Go to Learn |
 | `/` | Focus search |
 | `j` / `k` | Navigate up/down in resource list |
 | `[` / `]` | Previous/next service |
@@ -227,12 +263,13 @@ Press `?` anywhere to see all shortcuts.
 | `STACKPORT_PORT` | `8080` | StackPort server port |
 | `STACKPORT_ALLOW_WRITES` | `true` | Enable write operations (POST/PUT/DELETE) |
 | `STACKPORT_S3_MAX_UPLOAD_MB` | `100` | Max S3 upload size per object (MiB) |
+| `STACKPORT_LEARN` | `true` | Guided tutorials. `false` removes the Learn routes and UI |
 | `STACKPORT_SERVICES` | *(35 services)* | Comma-separated list of services to probe |
 | `STACKPORT_PROBE_TIMEOUT` | `5` | Seconds before a service probe times out |
 | `STACKPORT_CACHE_TTL` | `5` | Seconds to cache service stats |
 | `STACKPORT_PROBE_WORKERS` | `10` | Max concurrent workers for service probing |
 | `STACKPORT_ENDPOINTS` | *(unset)* | Multiple endpoints: `local=http://localhost:4566,staging=http://...` |
-| `STACKPORT_DATA_DIR` | `~/.stackport` | Directory for persistent config (endpoints.json) |
+| `STACKPORT_DATA_DIR` | `~/.stackport` | Directory for persistent config (endpoints.json, learn_progress.json) |
 | `LOG_LEVEL` | `INFO` | Python log level (`DEBUG` shows healthcheck logs) |
 
 ## Supported Services (35)
@@ -297,6 +334,10 @@ ui/src/
   lib/             API client, types, service icons, utils
 ```
 
+## Origin
+
+StackPort started as a web UI pull request to [MiniStack](https://github.com/ministackorg/ministack) ([ministack#116](https://github.com/ministackorg/ministack/pull/116)). The MiniStack maintainers suggested it would be more useful as a standalone tool that talks to any emulator over the standard AWS API, and that is what it became. Thanks to [@Nahuel990](https://github.com/Nahuel990) and [@McDoit](https://github.com/McDoit) for pushing it in that direction.
+
 ## Contributors
 
 <a href="https://github.com/DaviReisVieira/stackport/graphs/contributors">

{stackport-0.4.1 → stackport-0.4.3}/backend/cli.py

@@ -10,13 +10,37 @@ import click
 import uvicorn
 
 from backend.aws_client import get_client
-from backend.config import AWS_ENDPOINT_URL, AWS_REGION, LOG_LEVEL, STACKPORT_PORT, STACKPORT_SERVICES
-from backend.routes.resources import DESCRIBE_REGISTRY, _extract_id, _serialize
+from backend.config import (
+    AWS_ENDPOINT_URL,
+    AWS_REGION,
+    LOG_LEVEL,
+    STACKPORT_PORT,
+    STACKPORT_SERVICES,
+    endpoint_store,
+)
+from backend.routes.resources import (
+    DESCRIBE_REGISTRY,
+    _PREFERRED_ID_FIELD,
+    _extract_id,
+    _serialize,
+)
 from backend.routes.stats import SERVICE_REGISTRY, _METHOD_KWARGS, _count_items, _probe_service
 
 logger = logging.getLogger(__name__)
 
 
+def _client_kwargs(endpoint: str | None, region: str | None) -> dict:
+    """Resolve where a CLI command talks to.
+
+    An explicit --endpoint (or AWS_ENDPOINT_URL at startup) wins. Without one,
+    fall back to the saved default endpoint, the same one the web UI uses.
+    Passing the result to get_client explicitly is what makes the flag work
+    once ~/.stackport/endpoints.json exists.
+    """
+    url = endpoint if endpoint is not None else endpoint_store.get_default_url()
+    return {"endpoint_url": url, "region": region}
+
+
 @click.group(invoke_without_command=True)
 @click.version_option(package_name="stackport")
 @click.pass_context
@@ -39,22 +63,14 @@ def serve(port):
 @click.option("--output", type=click.Choice(["json", "table"]), default="table", help="Output format")
 def status(endpoint, region, output):
     """Show all services with availability and resource counts."""
-    # Override endpoint/region if provided
-    if endpoint != AWS_ENDPOINT_URL:
-        import os
-
-        os.environ["AWS_ENDPOINT_URL"] = endpoint
-    if region != AWS_REGION:
-        import os
-
-        os.environ["AWS_REGION"] = region
+    client_kwargs = _client_kwargs(endpoint, region)
 
     enabled_services = [s.strip() for s in STACKPORT_SERVICES.split(",") if s.strip()]
     services = {}
 
     try:
         with ThreadPoolExecutor(max_workers=min(len(enabled_services), 10)) as executor:
-            futures = {executor.submit(_probe_service, svc): svc for svc in enabled_services}
+            futures = {executor.submit(_probe_service, svc, **client_kwargs): svc for svc in enabled_services}
             for future in as_completed(futures):
                 svc_name, result = future.result()
                 services[svc_name] = result
@@ -89,15 +105,7 @@ def status(endpoint, region, output):
 @click.option("--output", type=click.Choice(["json", "table", "csv"]), default="table", help="Output format")
 def list(service, endpoint, region, output):
     """List resources for a service."""
-    # Override endpoint/region if provided
-    if endpoint != AWS_ENDPOINT_URL:
-        import os
-
-        os.environ["AWS_ENDPOINT_URL"] = endpoint
-    if region != AWS_REGION:
-        import os
-
-        os.environ["AWS_REGION"] = region
+    client_kwargs = _client_kwargs(endpoint, region)
 
     registry_entries = SERVICE_REGISTRY.get(service)
     if not registry_entries:
@@ -109,7 +117,7 @@ def list(service, endpoint, region, output):
     resources = {}
     for resource_type, boto3_service, method_name, response_key in registry_entries:
         try:
-            client = get_client(boto3_service)
+            client = get_client(boto3_service, **client_kwargs)
             method = getattr(client, method_name)
             kwargs = _METHOD_KWARGS.get((boto3_service, method_name), {})
             resp = method(**kwargs)
@@ -129,8 +137,9 @@ def list(service, endpoint, region, output):
         writer = csv.writer(sys.stdout)
         writer.writerow(["service", "resource_type", "resource_id", "name"])
         for resource_type, items in resources.items():
+            preferred = _PREFERRED_ID_FIELD.get((service, resource_type))
             for item in items:
-                resource_id = _extract_id(item)
+                resource_id = _extract_id(item, preferred)
                 name = item.get("Name", item.get("FunctionName", item.get("TableName", resource_id))) if isinstance(item, dict) else resource_id
                 writer.writerow([service, resource_type, resource_id, name])
     else:
@@ -139,8 +148,9 @@ def list(service, endpoint, region, output):
             if items:
                 click.echo(f"\n{resource_type.upper()} ({len(items)}):")
                 click.echo("-" * 60)
+                preferred = _PREFERRED_ID_FIELD.get((service, resource_type))
                 for item in items[:20]:  # Limit to first 20 for readability
-                    resource_id = _extract_id(item)
+                    resource_id = _extract_id(item, preferred)
                     if isinstance(item, dict):
                         name = item.get("Name", item.get("FunctionName", item.get("TableName", "")))
                         if name and name != resource_id:
@@ -164,20 +174,12 @@ def list(service, endpoint, region, output):
 @click.option("--output", type=click.Choice(["json", "table"]), default="json", help="Output format")
 def describe(service, resource_type, resource_id, endpoint, region, output):
     """Describe a specific resource."""
-    # Override endpoint/region if provided
-    if endpoint != AWS_ENDPOINT_URL:
-        import os
-
-        os.environ["AWS_ENDPOINT_URL"] = endpoint
-    if region != AWS_REGION:
-        import os
-
-        os.environ["AWS_REGION"] = region
+    client_kwargs = _client_kwargs(endpoint, region)
 
     # Special case for WAFv2
     if (service, resource_type) == ("wafv2", "web_acls"):
         try:
-            client = get_client("wafv2")
+            client = get_client("wafv2", **client_kwargs)
             acls = client.list_web_acls(Scope="REGIONAL").get("WebACLs", [])
             match = next((a for a in acls if a.get("Name") == resource_id), None)
             if not match:
@@ -211,7 +213,7 @@ def describe(service, resource_type, resource_id, endpoint, region, output):
         }
 
         try:
-            client = get_client(boto3_service)
+            client = get_client(boto3_service, **client_kwargs)
             method = getattr(client, method_name)
             if id_param in _LIST_PARAMS:
                 resp = method(**{id_param: [resource_id]})

{stackport-0.4.1 → stackport-0.4.3}/backend/config.py

@@ -16,6 +16,9 @@ AWS_ACCESS_KEY_ID: str | None = os.environ.get("AWS_ACCESS_KEY_ID")
 AWS_SECRET_ACCESS_KEY: str | None = os.environ.get("AWS_SECRET_ACCESS_KEY")
 STACKPORT_ALLOW_WRITES: bool = os.environ.get("STACKPORT_ALLOW_WRITES", "true").lower() in ("1", "true", "yes")
 STACKPORT_PORT: int = int(os.environ.get("STACKPORT_PORT", "8080"))
+# Guided tutorials. Set to false to drop the Learn routes and every trace of
+# the tutorial UI, for anyone who wants StackPort as a resource browser only.
+STACKPORT_LEARN: bool = os.environ.get("STACKPORT_LEARN", "true").lower() in ("1", "true", "yes")
 STACKPORT_SERVICES: str = os.environ.get(
     "STACKPORT_SERVICES",
     "s3,sqs,sns,dynamodb,lambda,iam,logs,ssm,secretsmanager,kinesis,events,ec2,"

stackport-0.4.3/backend/learn/__init__.py

@@ -0,0 +1 @@
+"""Learn module: guided AWS trails verified against live emulator state."""

stackport-0.4.3/backend/learn/content.py

@@ -0,0 +1,107 @@
+"""Validation for authored trail content.
+
+A typo in a trail JSON file, a verification type that does not exist or a step
+pointing at a hotspot the UI never renders would all strand a learner mid
+lesson with no way forward. Content is therefore validated when it loads, and
+the test suite runs the same validation over everything that ships, so bad
+content fails in CI instead of in front of someone trying to learn.
+"""
+
+import re
+
+from backend.learn.hotspots import KNOWN_HOTSPOT_IDS
+from backend.learn.verify import CHECKS
+
+_PLACEHOLDER_RE = re.compile(r"\{\{(\w+)\}\}")
+
+# Filled in by the server rather than declared by a lesson
+_IMPLICIT_VARIABLES = frozenset({"endpointUrl"})
+
+_TRAIL_KEYS = ("id", "title", "description", "lessons")
+_LESSON_KEYS = ("id", "title", "summary", "steps")
+_STEP_KEYS = ("id", "title", "instruction")
+
+
+def _require(data: dict, keys: tuple[str, ...], where: str) -> None:
+    missing = [key for key in keys if key not in data]
+    if missing:
+        raise ValueError(f"{where} is missing {', '.join(missing)}")
+
+
+def _validate_verify(spec: dict, where: str) -> None:
+    check_type = spec.get("type")
+    if check_type not in CHECKS:
+        raise ValueError(f"{where} uses unknown verify type '{check_type}'")
+    if check_type == "all_of":
+        for nested in spec.get("params", {}).get("checks", []):
+            _validate_verify(nested, f"{where} (nested)")
+
+
+def validate_trail(trail: dict) -> None:
+    """Raise ValueError describing the first problem found, if any."""
+    _require(trail, _TRAIL_KEYS, "trail")
+    if not trail["lessons"]:
+        raise ValueError(f"trail '{trail['id']}' has no lessons")
+
+    lesson_ids: set[str] = set()
+    for lesson in trail["lessons"]:
+        _require(lesson, _LESSON_KEYS, f"lesson in trail '{trail['id']}'")
+        where_lesson = f"{trail['id']}/{lesson['id']}"
+        if lesson["id"] in lesson_ids:
+            raise ValueError(f"duplicate lesson id '{lesson['id']}' in trail '{trail['id']}'")
+        lesson_ids.add(lesson["id"])
+
+        declared = {spec["name"] for spec in lesson.get("variables", [])} | _IMPLICIT_VARIABLES
+        for spec in lesson.get("variables", []):
+            if "default" not in spec:
+                raise ValueError(f"variable '{spec['name']}' in {where_lesson} has no default")
+
+        if not lesson["steps"]:
+            raise ValueError(f"lesson {where_lesson} has no steps")
+
+        # everything except the variable specs, whose defaults carry {{suffix}}
+        body = {key: value for key, value in lesson.items() if key != "variables"}
+        for name in _placeholders(body) - declared:
+            raise ValueError(f"lesson {where_lesson} uses undeclared variable '{{{{{name}}}}}'")
+
+        step_ids: set[str] = set()
+        hotspot_ids: set[str] = set()
+        for step in lesson["steps"]:
+            _require(step, _STEP_KEYS, f"step in lesson {where_lesson}")
+            where = f"{where_lesson}/{step['id']}"
+            if step["id"] in step_ids:
+                raise ValueError(f"duplicate step id '{step['id']}' in lesson {where_lesson}")
+            step_ids.add(step["id"])
+
+            if step.get("verify"):
+                _validate_verify(step["verify"], where)
+
+            console = step.get("console")
+            if console:
+                hotspot_id = console.get("hotspotId")
+                if hotspot_id and hotspot_id not in KNOWN_HOTSPOT_IDS:
+                    raise ValueError(f"{where} points at unknown hotspot '{hotspot_id}'")
+                if hotspot_id in hotspot_ids:
+                    # two steps sharing an anchor would unlock the second one's
+                    # Next button as soon as the first one mounted
+                    raise ValueError(f"{where} reuses hotspot '{hotspot_id}' within the same lesson")
+                if hotspot_id:
+                    hotspot_ids.add(hotspot_id)
+                if not console.get("route"):
+                    raise ValueError(f"{where} has a console path with no route")
+
+            for name in _placeholders(step) - declared:
+                raise ValueError(f"{where} uses undeclared variable '{{{{{name}}}}}'")
+
+
+def _placeholders(value: object) -> set[str]:
+    found: set[str] = set()
+    if isinstance(value, str):
+        found.update(_PLACEHOLDER_RE.findall(value))
+    elif isinstance(value, dict):
+        for nested in value.values():
+            found |= _placeholders(nested)
+    elif isinstance(value, list):
+        for nested in value:
+            found |= _placeholders(nested)
+    return found

stackport-0.4.3/backend/learn/hotspots.py

@@ -0,0 +1,27 @@
+"""Hotspot ids a lesson step may point at.
+
+A hotspot is an anchor rendered by the frontend next to a real control, which
+the tutorial popover attaches to. The ids live here because trail content is
+validated on the backend, and are mirrored in
+ui/src/components/cloudscape/learn/hotspots.ts, where the anchors are actually
+rendered. A frontend test reads this file and fails if the two lists drift, so
+keep it plain data: one string literal per line, no logic.
+
+Naming: {scope}-{noun}-{action}.
+"""
+
+KNOWN_HOTSPOT_IDS: frozenset[str] = frozenset(
+    {
+        # shell
+        "learn-panel-anchor",
+        "nav-resources",
+        # s3
+        "s3-buckets-create",
+        "s3-buckets-table",
+        "s3-upload",
+        "s3-objects-table",
+        # dynamodb
+        "dynamodb-tables-create",
+        "dynamodb-tables-table",
+    }
+)