stackport 0.4.1__tar.gz → 0.4.2__tar.gz

stackport-0.4.2/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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackport
-Version: 0.4.1
+Version: 0.4.2
 Summary: Universal AWS resource browser for local emulators
 Author: Davi Reis Vieira
 License: MIT
@@ -70,6 +70,7 @@ 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
@@ -206,6 +207,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 +260,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 +280,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)

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

@@ -34,6 +34,7 @@
 - **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
@@ -170,6 +171,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 +224,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 +244,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)

{stackport-0.4.1 → stackport-0.4.2}/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.2/backend/learn/__init__.py

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

stackport-0.4.2/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.2/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",
+    }
+)

stackport-0.4.2/backend/learn/trails/aws-first-steps.json

@@ -0,0 +1,171 @@
+{
+  "id": "aws-first-steps",
+  "title": "AWS first steps",
+  "description": "Learn core AWS services by building against your local emulator. You do the work in the console or the CLI, and StackPort checks the real resource state, so a step only turns green when the thing genuinely exists. Nothing here costs money or touches a real account.",
+  "lessons": [
+    {
+      "id": "s3-store-a-file",
+      "title": "Store a file",
+      "summary": "Create a bucket, put a file in it, and read back what S3 recorded about it.",
+      "service": "s3",
+      "level": "Beginner",
+      "durationMinutes": 6,
+      "docsUrl": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html",
+      "variables": [
+        {
+          "name": "bucket",
+          "label": "Your bucket name",
+          "default": "stackport-learn-{{suffix}}",
+          "description": "You will create this bucket, and every command in the lesson will use the name you pick.",
+          "pattern": "^[a-z0-9][a-z0-9-]{1,40}[a-z0-9]$",
+          "patternMessage": "Bucket names use lowercase letters, numbers and hyphens, and must start and end with a letter or number."
+        }
+      ],
+      "steps": [
+        {
+          "id": "find-s3",
+          "title": "Find S3",
+          "instruction": "S3 is where AWS keeps files. Not a filesystem and not a disk you attach to a server: a service you send files to over HTTP, one file at a time, and it hands them back on request.\n\nOpen the S3 view. This is the same navigation you would use in the AWS console, and the list you are about to see is read live from your emulator.",
+          "console": {
+            "hotspotId": "nav-resources",
+            "route": "/resources/s3",
+            "label": "Resources, then S3 in the service list"
+          },
+          "commands": {
+            "cli": "aws --endpoint-url={{endpointUrl}} s3 ls"
+          },
+          "cliNotes": [
+            {
+              "flag": "--endpoint-url",
+              "note": "Points the CLI at your emulator instead of real AWS. Drop this one flag and the exact same command talks to a real account. It is worth staring at for a second, because it is the only difference."
+            },
+            {
+              "flag": "s3 ls",
+              "note": "With nothing after it, lists your buckets. With a bucket name after it, lists what is inside."
+            }
+          ],
+          "whyItMatters": "Every AWS API call goes to a URL. The CLI normally computes that URL from the service and the region, which is why you never see it. Overriding it is what makes local emulators possible, and also what makes a mistyped endpoint fail in confusing ways.",
+          "verify": null,
+          "hint": "Empty output is the correct answer if you have no buckets yet."
+        },
+        {
+          "id": "create-bucket",
+          "title": "Create your bucket",
+          "instruction": "A bucket is a named container, and the name is the part that matters. Bucket names live in one namespace shared by everyone using that AWS partition, which is why they are lowercase, DNS-shaped, and frequently already taken.\n\nCreate a bucket called {{bucket}}. Your emulator has no global namespace to collide with, but the naming rules are enforced anyway, because a name that works locally and is rejected in production is a bad lesson to learn twice.",
+          "console": {
+            "hotspotId": "s3-buckets-create",
+            "route": "/resources/s3",
+            "label": "Create bucket",
+            "fields": [
+              { "label": "Bucket name", "value": "{{bucket}}" }
+            ]
+          },
+          "commands": {
+            "cli": "aws --endpoint-url={{endpointUrl}} s3api create-bucket --bucket {{bucket}}"
+          },
+          "cliNotes": [
+            {
+              "flag": "s3api",
+              "note": "The one-to-one mapping onto the S3 API. `aws s3` is a friendlier layer on top with commands like cp and sync; `aws s3api` is what the API actually offers, which is what you want when you are learning what a service does."
+            },
+            {
+              "flag": "--bucket",
+              "note": "The name. In any region other than us-east-1 you would also need --create-bucket-configuration LocationConstraint=<region>, an old quirk of the API rather than a rule you can reason out."
+            }
+          ],
+          "whyItMatters": "Real S3 applies two defaults here that are worth knowing: server-side encryption with S3-managed keys is on and cannot be turned off, and Block Public Access is on for all four settings. If you ever find yourself switching that second one off, be certain you meant to.",
+          "verify": {
+            "type": "s3_bucket_exists",
+            "params": { "bucket": "{{bucket}}" }
+          },
+          "autoVerify": true,
+          "hint": "The name has to match {{bucket}} exactly, since that is what gets checked. If the command hangs instead of failing, your emulator is probably not running.",
+          "docsUrl": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html"
+        },
+        {
+          "id": "open-bucket",
+          "title": "Look inside it",
+          "instruction": "Open {{bucket}}. It is empty, which is the point worth pausing on: you created a container and paid for nothing, because S3 bills for the bytes you store and the requests you make, not for the bucket.\n\nA bucket is also flat. There are no directories inside it, only objects whose names happen to contain slashes.",
+          "console": {
+            "hotspotId": "s3-buckets-table",
+            "route": "/resources/s3",
+            "label": "Click {{bucket}} in the bucket list"
+          },
+          "commands": {
+            "cli": "aws --endpoint-url={{endpointUrl}} s3 ls s3://{{bucket}}"
+          },
+          "whyItMatters": "The flatness is not a detail. When a console shows you a folder called photos/, it is showing you every key beginning with \"photos/\" grouped under a heading it invented for the occasion. Listing 10,000 objects in one prefix costs the same as listing them across ten, and renaming a \"folder\" means copying every object to a new key.",
+          "verify": null,
+          "hint": "Nothing to see yet is the expected result. Mark this done and go put something in it."
+        },
+        {
+          "id": "upload-object",
+          "title": "Put a file in it",
+          "instruction": "Store a file called hello.txt in {{bucket}}. Its name inside the bucket is its key, and the key is the whole address: bucket plus key identifies exactly one object.\n\nIn the console, use the upload control. From the CLI, create a file first and copy it up.",
+          "console": {
+            "hotspotId": "s3-upload",
+            "route": "/resources/s3",
+            "label": "Upload, then pick any small text file and name it hello.txt",
+            "fields": [
+              { "label": "Key", "value": "hello.txt" }
+            ]
+          },
+          "commands": {
+            "cli": "echo \"hello from stackport\" > hello.txt\naws --endpoint-url={{endpointUrl}} s3 cp hello.txt s3://{{bucket}}/hello.txt"
+          },
+          "cliNotes": [
+            {
+              "flag": "s3 cp",
+              "note": "Copies one thing. Its sibling `s3 sync` compares a whole directory against a prefix and transfers only what differs, which is the one you want for deployments."
+            },
+            {
+              "flag": "s3://{{bucket}}/hello.txt",
+              "note": "Bucket and key. Change the last part and you have stored a different object: S3 has no rename, only copy and delete."
+            }
+          ],
+          "verify": {
+            "type": "s3_object_exists",
+            "params": { "bucket": "{{bucket}}", "key": "hello.txt" }
+          },
+          "autoVerify": true,
+          "hint": "The key must be exactly hello.txt, at the top of the bucket rather than inside a prefix.",
+          "docsUrl": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html"
+        },
+        {
+          "id": "inspect-object",
+          "title": "Read what S3 recorded",
+          "instruction": "Open hello.txt and look at its metadata. Three fields are worth your attention.\n\n**Size** is what you are billed for, to the byte. **Content type** is what S3 will claim the file is when someone downloads it, and it is a guess made at upload time. **ETag** is a fingerprint of the content, which is how you can tell two objects apart without downloading either.",
+          "console": {
+            "hotspotId": "s3-objects-table",
+            "route": "/resources/s3",
+            "label": "Click hello.txt to open its details"
+          },
+          "commands": {
+            "cli": "aws --endpoint-url={{endpointUrl}} s3api head-object --bucket {{bucket}} --key hello.txt"
+          },
+          "cliNotes": [
+            {
+              "flag": "head-object",
+              "note": "Returns the metadata without the body, the same way an HTTP HEAD request does. Cheap, and the fastest way to answer \"is this object there and has it changed?\"."
+            }
+          ],
+          "whyItMatters": "Content type is the field that will eventually bite you. Upload an image with the wrong one and browsers download it instead of showing it; upload HTML as text/plain and visitors read your markup. S3 infers it from the file extension at upload time and never revisits that guess, so fixing it later means copying the object over itself with the right value.",
+          "verify": null,
+          "hint": "You are looking for size in bytes, content type, and ETag. Mark this done once you have found all three.",
+          "docsUrl": "https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html"
+        }
+      ],
+      "completion": {
+        "title": "You built something real",
+        "summary": "Your emulator now holds a bucket named {{bucket}} with hello.txt inside it. Not a simulation of one: the same API calls, the same naming rules, the same metadata you would get from real S3.",
+        "takeaways": [
+          "A bucket is a named container in a shared namespace, and the name is the hard part.",
+          "An object is addressed by bucket plus key, and there are no folders, only keys with slashes in them.",
+          "Metadata is data: size is your bill, content type is a guess, and ETag is a fingerprint.",
+          "One flag, --endpoint-url, is all that separates a local command from one that hits a real account."
+        ],
+        "nextHint": "Everything you just created is still there. Delete it with `aws --endpoint-url={{endpointUrl}} s3 rb s3://{{bucket}} --force`, or leave it and keep poking at it."
+      }
+    }
+  ]
+}

stackport-0.4.2/backend/learn/verify.py

@@ -0,0 +1,172 @@
+"""Step verification for the Learn module.
+
+Checks run directly against the selected endpoint with fresh boto3 calls
+(never through the TTL cache) so a step verifies immediately after the
+learner acts. Connection failures surface as status "service_unreachable"
+instead of a silent "not done".
+"""
+
+import logging
+from collections.abc import Callable
+
+from botocore.exceptions import ClientError, ConnectTimeoutError, EndpointConnectionError
+
+from backend.aws_client import get_client
+from backend.routes.common import EndpointInfo
+
+logger = logging.getLogger(__name__)
+
+
+def _s3_bucket_exists(ep: EndpointInfo, params: dict) -> dict:
+    bucket = params["bucket"]
+    client = get_client("s3", **ep.client_kwargs())
+    try:
+        client.head_bucket(Bucket=bucket)
+        return {"passed": True, "message": f"Bucket '{bucket}' found."}
+    except ClientError:
+        return {"passed": False, "message": f"Bucket '{bucket}' not found yet."}
+
+
+def _s3_object_exists(ep: EndpointInfo, params: dict) -> dict:
+    """One named object. Better UX than a count: the message can say what is missing."""
+    bucket = params["bucket"]
+    key = params["key"]
+    client = get_client("s3", **ep.client_kwargs())
+    try:
+        response = client.head_object(Bucket=bucket, Key=key)
+    except ClientError:
+        return {"passed": False, "message": f"No object '{key}' in '{bucket}' yet."}
+    size = response.get("ContentLength", 0)
+    return {"passed": True, "message": f"Found '{key}' in '{bucket}' ({size} bytes)."}
+
+
+def _s3_prefix_exists(ep: EndpointInfo, params: dict) -> dict:
+    """A prefix "exists" when at least one key starts with it (S3 has no real folders)."""
+    bucket = params["bucket"]
+    prefix = params["prefix"]
+    client = get_client("s3", **ep.client_kwargs())
+    try:
+        response = client.list_objects_v2(Bucket=bucket, Prefix=prefix, MaxKeys=1)
+    except ClientError:
+        return {"passed": False, "message": f"Bucket '{bucket}' not found yet."}
+    if response.get("KeyCount", 0) > 0:
+        return {"passed": True, "message": f"Found keys under '{prefix}' in '{bucket}'."}
+    return {"passed": False, "message": f"Nothing stored under '{prefix}' in '{bucket}' yet."}
+
+
+def _s3_object_count(ep: EndpointInfo, params: dict) -> dict:
+    bucket = params["bucket"]
+    minimum = int(params.get("min", 1))
+    client = get_client("s3", **ep.client_kwargs())
+    try:
+        response = client.list_objects_v2(Bucket=bucket)
+    except ClientError:
+        return {"passed": False, "message": f"Bucket '{bucket}' not found yet."}
+    count = response.get("KeyCount", 0)
+    if count >= minimum:
+        return {"passed": True, "message": f"Found {count} object(s) in '{bucket}'."}
+    return {"passed": False, "message": f"Bucket '{bucket}' has {count} object(s); expected at least {minimum}."}
+
+
+def _dynamodb_table_exists(ep: EndpointInfo, params: dict) -> dict:
+    table = params["table"]
+    client = get_client("dynamodb", **ep.client_kwargs())
+    try:
+        response = client.describe_table(TableName=table)
+    except ClientError:
+        return {"passed": False, "message": f"Table '{table}' not found yet."}
+    status = response.get("Table", {}).get("TableStatus", "")
+    expected_status = params.get("status")
+    if expected_status and status != expected_status:
+        return {"passed": False, "message": f"Table '{table}' exists but is {status}, expected {expected_status}."}
+    return {"passed": True, "message": f"Table '{table}' found ({status})."}
+
+
+def _dynamodb_item_count(ep: EndpointInfo, params: dict) -> dict:
+    table = params["table"]
+    minimum = int(params.get("min", 1))
+    client = get_client("dynamodb", **ep.client_kwargs())
+    try:
+        response = client.scan(TableName=table, Select="COUNT")
+    except ClientError:
+        return {"passed": False, "message": f"Table '{table}' not found yet."}
+    count = response.get("Count", 0)
+    if count >= minimum:
+        return {"passed": True, "message": f"Found {count} item(s) in '{table}'."}
+    return {"passed": False, "message": f"Table '{table}' has {count} item(s); expected at least {minimum}."}
+
+
+def _resource_exists(ep: EndpointInfo, params: dict) -> dict:
+    """Generic existence check driven by SERVICE_REGISTRY (no cache)."""
+    from backend.routes.stats import _METHOD_KWARGS, SERVICE_REGISTRY
+
+    service = params["service"]
+    resource_type = params["resource_type"]
+    target = params["id"]
+
+    for rtype, boto_service, method, response_key in SERVICE_REGISTRY.get(service, []):
+        if rtype != resource_type:
+            continue
+        client = get_client(boto_service, **ep.client_kwargs())
+        kwargs = _METHOD_KWARGS.get((boto_service, method), {})
+        response = getattr(client, method)(**kwargs)
+        items = response.get(response_key, [])
+        if isinstance(items, dict) and "Items" in items:
+            items = items["Items"]
+        for item in items:
+            if isinstance(item, str) and target in item:
+                return {"passed": True, "message": f"Found {resource_type[:-1] if resource_type.endswith('s') else resource_type} '{target}'."}
+            if isinstance(item, dict) and any(target in str(v) for v in item.values() if isinstance(v, str)):
+                return {"passed": True, "message": f"Found '{target}' in {service} {resource_type}."}
+        return {"passed": False, "message": f"'{target}' not found in {service} {resource_type} yet."}
+    return {"passed": False, "message": f"Unknown resource type {service}/{resource_type}."}
+
+
+def _all_of(ep: EndpointInfo, params: dict) -> dict:
+    """Composite step: every nested check must pass. Reports the first one that doesn't."""
+    specs = params.get("checks", [])
+    if not specs:
+        return {"passed": False, "message": "This composite check has no sub-checks."}
+    for spec in specs:
+        check = CHECKS.get(spec.get("type", ""))
+        if check is None:
+            return {"passed": False, "message": f"Unknown check type '{spec.get('type')}'."}
+        result = check(ep, spec.get("params", {}))
+        if not result["passed"]:
+            return result
+    return {"passed": True, "message": f"All {len(specs)} conditions met."}
+
+
+CHECKS: dict[str, Callable[[EndpointInfo, dict], dict]] = {
+    "s3_bucket_exists": _s3_bucket_exists,
+    "s3_object_exists": _s3_object_exists,
+    "s3_prefix_exists": _s3_prefix_exists,
+    "s3_object_count": _s3_object_count,
+    "all_of": _all_of,
+    "dynamodb_table_exists": _dynamodb_table_exists,
+    "dynamodb_item_count": _dynamodb_item_count,
+    "resource_exists": _resource_exists,
+}
+
+
+def run_check(ep: EndpointInfo, spec: dict) -> dict:
+    """Run a verification spec: {"type": <check name>, "params": {...}}.
+
+    Returns {"status": "ok"|"service_unreachable"|"error", "passed": bool, "message": str}.
+    """
+    check = CHECKS.get(spec.get("type", ""))
+    if check is None:
+        return {"status": "error", "passed": False, "message": f"Unknown check type '{spec.get('type')}'."}
+    try:
+        result = check(ep, spec.get("params", {}))
+        result["status"] = "ok"
+        return result
+    except (EndpointConnectionError, ConnectTimeoutError):
+        return {
+            "status": "service_unreachable",
+            "passed": False,
+            "message": "Could not reach the endpoint. Is your emulator running?",
+        }
+    except Exception as e:
+        logger.debug("Learn check failed unexpectedly", exc_info=True)
+        return {"status": "error", "passed": False, "message": str(e)}