@topy-ai/maggie 0.7.52 → 0.7.54

package/bundled-skills/maggie-social-share/references/queue-and-connections.md

@@ -115,6 +115,34 @@ An adapter that publishes must declare, in addition to its scope set:
 
 Adapters without `publishes` keep the scope-only shape.
 
+## Posted-post lifecycle
+
+**Post now.** Claim the item atomically before calling the provider
+(`UPDATE ... SET status = 'publishing' WHERE id = $1 AND status IN
+('queued','approved') RETURNING ...`); a second click or another worker gets
+no row and does nothing. On a provider failure restore the previous status
+(and its slot); on an unknown outcome (timeout) leave it `publishing` for
+`reconcile`.
+
+**Delete a published post.** Delete on the provider first, then mark the
+item `deleted` with the time and who did it. A provider 404 means it is
+already gone: mark it deleted. Never delete the local record while the
+provider post still exists.
+
+**Edit and republish.** Most providers cannot edit a post, so an edit is a
+new post replacing the old one. Order matters — never take the old post down
+when the new one cannot go out:
+
+1. Pre-check everything: the source article is still published on the
+   workspace's own domain, the copy with the link fits the limit, the image
+   (if any) is present and accepted, the connection is healthy.
+2. Publish the new post (same idempotency rules as any publish).
+3. Only after the new post is confirmed, delete the old one; if that delete
+   fails, keep both recorded and retry the delete — do not roll back the new
+   post.
+4. If step 2 fails, nothing changed: the old post stays and the item returns
+   to its previous state with the error.
+
 ## Publish reconciliation — `reconcile`
 
 `reconcile` reads the publish-attempt log and a provider readback and returns

package/bundled-tools/clis/maggie_assistant_tools.py

@@ -18,7 +18,7 @@ code or call a model.
   a readable summary (never a bare UUID) and the right scope (account-level
   writes are not filed under the open site).
 - ``approval-selftest``: exercises the reference signed one-time approval
-  token (``tools/runtime/assistant_approval.py``).
+  token and standing workflow approvals (``tools/runtime/assistant_approval.py``).
 """
 
 from __future__ import annotations
@@ -34,8 +34,9 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 SCHEMA = "maggie-assistant-tool-registry.v1"
 RISKS = ("read", "write-reversible", "write-spends", "write-public", "never")
 RISK_ALIASES = {"R0": "read", "W1": "write-reversible", "W2": "write-spends", "W3": "write-public", "W4": "never"}
-CHANNELS = ("in-app", "mcp", "chatgpt", "claude", "cli")
+CHANNELS = ("in-app", "mcp", "chatgpt", "claude", "cli", "web-widget")
 SCOPES = ("account", "workspace")
+CARDS = ("place", "slot-picker", "booking", "voucher", "change-preview", "numbers", "draft", "list")
 NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$|^[a-z][a-z0-9]+$")
 SNAKE_RE = re.compile(r"\b[a-z][a-z0-9]*_[a-z0-9_]+\b")
 THE_USER_RE = re.compile(r"\bthe user('s)?\b", re.I)
@@ -74,6 +75,31 @@ def validate_registry(registry: dict) -> dict:
     for duplicate in sorted({name for name in names if names.count(name) > 1}):
         errors.append(f"duplicate tool name {duplicate}")
     counts = {risk: 0 for risk in RISKS}
+    servers = {}
+    for server in registry.get("mcpServers", []) or []:
+        if not isinstance(server, dict) or not server.get("name"):
+            errors.append("mcpServers entries need a name"); continue
+        name = str(server["name"])
+        servers[name] = server
+        if server.get("auth") not in {"none", "oauth"}:
+            errors.append(f"MCP server {name}: auth must be none (public, read-only) or oauth")
+        elif server["auth"] == "none":
+            limit = server.get("rateLimit") if isinstance(server.get("rateLimit"), dict) else {}
+            if not limit.get("perIpPerMinute") and not limit.get("perIpPerDay"):
+                errors.append(f"MCP server {name}: a public server needs rateLimit (perIpPerMinute and/or perIpPerDay)")
+        else:
+            if not str(server.get("resource", "")).startswith("https://"):
+                errors.append(f"MCP server {name}: resource must be the server's canonical https URL (the token audience)")
+            if server.get("audienceBinding", True) is not True and not str(server.get("audienceException", "")).strip():
+                errors.append(f"MCP server {name}: audience binding is on by default (RFC 8707); turning it off needs audienceException with the reason")
+    threads = registry.get("threads") if isinstance(registry.get("threads"), dict) else None
+    if threads and threads.get("storage") == "server":
+        if not isinstance(threads.get("retentionDays"), int) or threads["retentionDays"] < 1:
+            errors.append("threads.retentionDays is required for server-stored conversations")
+        if threads.get("deleteOnAccountDeletion") is not True:
+            errors.append("threads.deleteOnAccountDeletion must be true for server-stored conversations")
+        if threads.get("supportAccess") not in {"none", "with-consent"}:
+            errors.append("threads.supportAccess must be none or with-consent")
     for tool in tools:
         if not isinstance(tool, dict):
             errors.append("each tool must be an object"); continue
@@ -122,13 +148,47 @@ def validate_registry(registry: dict) -> dict:
             warnings.append(f"{where}: the name reads as destructive; app reviewers expect destructiveHint, so consider write-public")
         if tool.get("audit", {}).get("scope") not in (None, tool.get("scope")):
             errors.append(f"{where}: audit.scope must equal the tool scope (an account-level write is not audited under the open site)")
+        card = tool.get("card")
+        if card is not None and card not in CARDS:
+            errors.append(f"{where}: card must be one of {', '.join(CARDS)}")
+        if card == "change-preview" and risk == "read":
+            warnings.append(f"{where}: a change-preview card belongs to a write (it shows what will change before approval)")
+        for server in tool.get("mcpServers", []) or []:
+            if server not in servers:
+                errors.append(f"{where}: mcpServers lists {server!r}, which is not declared in registry.mcpServers")
+            elif servers[server].get("auth") == "none" and risk != "read":
+                errors.append(f"{where}: a public (unauthenticated) MCP server may only expose read tools")
+            elif servers[server].get("auth") == "none" and tool.get("scope") == "account":
+                errors.append(f"{where}: account-scoped tools need a signed-in caller; keep them off the public MCP server")
     for item in registry.get("cantDo", []) or []:
         if not isinstance(item, dict) or not str(item.get("text", "")).strip():
             errors.append("cantDo entries need text (and ideally 'instead')")
             continue
         for problem in user_copy_problems(str(item.get("text", "")) + " " + str(item.get("instead", "")), name_set):
             errors.append(f"cantDo '{str(item['text'])[:40]}': {problem}")
-    return {"schemaVersion": "maggie-assistant-registry-validation.v1", "passed": not errors, "errors": errors, "warnings": warnings, "counts": {"tools": len(tools), **counts}}
+    widget_tools = [t for t in tools if isinstance(t, dict) and "web-widget" in (t.get("channels") or [])]
+    if widget_tools:
+        # A visitor-facing assistant (an AI receptionist) answers strangers: no approvals are possible,
+        # so it only reads business facts, is off until the business turns it on, is capped and logged.
+        for tool in widget_tools:
+            if risk_of(tool) != "read":
+                errors.append(f"{tool.get('name')}: web-widget tools answer visitors and must be read-only; booking and payment stay in the normal booking sheet")
+            if tool.get("scope") == "account":
+                errors.append(f"{tool.get('name')}: web-widget tools act for one business (scope workspace), never on an account")
+        policy = registry.get("visitorPolicy") if isinstance(registry.get("visitorPolicy"), dict) else {}
+        if policy.get("enabledByDefault") is not False:
+            errors.append("visitorPolicy.enabledByDefault must be false: the business turns the receptionist on")
+        caps = policy.get("dailyCaps") if isinstance(policy.get("dailyCaps"), dict) else {}
+        if not caps.get("perVisitor") or not caps.get("perBusiness"):
+            errors.append("visitorPolicy.dailyCaps needs perVisitor and perBusiness (model spend and abuse)")
+        if policy.get("logAnswers") is not True:
+            errors.append("visitorPolicy.logAnswers must be true: the business can read every answer given in its name")
+        if policy.get("factsOnly") is not True:
+            errors.append("visitorPolicy.factsOnly must be true: answers come from the business's own facts, never general knowledge about prices or health")
+        if policy.get("cardDetails") != "never":
+            errors.append("visitorPolicy.cardDetails must be never: the chat never asks for or accepts card numbers")
+    public_tools = [t.get("name") for t in tools if isinstance(t, dict) and any(servers.get(s, {}).get("auth") == "none" for s in t.get("mcpServers", []) or [])]
+    return {"schemaVersion": "maggie-assistant-registry-validation.v1", "passed": not errors, "errors": errors, "warnings": warnings, "counts": {"tools": len(tools), **counts, "cards": sum(1 for t in tools if isinstance(t, dict) and t.get("card")), "publicMcpTools": len(public_tools)}}
 
 
 def annotations_for(tool: dict) -> dict:
@@ -224,6 +284,8 @@ def audit_check(registry: dict, session: dict) -> dict:
         expected_scope = "account" if tool.get("scope") == "account" else call.get("workspace")
         if expected_scope and action.get("scope") != expected_scope:
             errors.append(f"{call.get('tool')}: audited under {action.get('scope')!r}, expected {expected_scope!r}")
+        if action.get("channel") == "workflow" and not action.get("standingApprovalId"):
+            errors.append(f"{call.get('tool')}: a workflow run must record the standing approval id it ran under")
         if call.get("ok") is False and not action.get("error"):
             errors.append(f"{call.get('tool')}: failed call has no audit error")
     return {"schemaVersion": "maggie-assistant-audit-check.v1", "passed": not errors, "errors": errors, "writes": sum(1 for c in calls if risk_of(tools.get(c.get("tool"), {})) not in {"read", ""})}
@@ -249,6 +311,25 @@ def approval_selftest() -> dict:
     results["scopeBound"] = raises(lambda: approval.verify(secret, token, "key-1", "site-b", calls, now=1001))
     results["tamperRejected"] = raises(lambda: approval.verify(secret, token[:-2] + ("AA" if not token.endswith("AA") else "BB"), "key-1", "site-a", calls, now=1001))
     results["idempotencyKeyStable"] = approval.idempotency_key(issued["id"], calls[0]) == approval.idempotency_key(issued["id"], dict(calls[0]))
+    # Standing approval: a waitlist workflow may send at most 2 offer e-mails a day with one template.
+    standing, grant = approval.issue_standing(secret, "owner-1", "site-a", "waitlist-fill", [{"name": "waitlist_offer_send", "maxPerDay": 2, "fixedArgs": {"template": "waitlist_offer"}}], days=30, now=1000)
+    store = approval.StandingStore()
+    offer = {"name": "waitlist_offer_send", "args": {"template": "waitlist_offer", "clientId": "c1"}}
+    first = store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-10-13", now=1001)
+    results["standingAllowsInsideLimits"] = first["auditChannel"] == "workflow" and first["approvalId"] == grant["id"]
+    store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-10-13", now=1001)
+    def falls_back(fn) -> bool:
+        try:
+            fn(); return False
+        except approval.OutsideStandingApproval:
+            return True
+    results["standingDailyLimit"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-10-13", now=1001))
+    results["standingArgsBound"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", {"name": "waitlist_offer_send", "args": {"template": "promo"}}, "2026-10-14", now=1001))
+    results["standingOtherTool"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", {"name": "booking_cancel", "args": {}}, "2026-10-14", now=1001))
+    results["standingExpires"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-12-01", now=1000 + 31 * 86400))
+    store.revoke(grant["id"])
+    results["standingRevocable"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-10-15", now=1001))
+    results["standingNotAOneTimeToken"] = raises(lambda: approval.verify(secret, standing, "owner-1", "site-a", [offer], now=1001))
     return {"schemaVersion": "maggie-assistant-approval-selftest.v1", "passed": all(results.values()), "checks": results}
 
 

package/bundled-tools/clis/maggie_booking.py

@@ -32,11 +32,9 @@ DEFAULT_OPS_EVIDENCE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-ops-evi
 DEFAULT_BROWSER_EVIDENCE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-browser-evidence-v2.json"
 DEFAULT_STRIPE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "stripe-booking-capabilities-v1.json"
 DEFAULT_VOUCHER_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-voucher-lifecycle-v1.json"
-EXECUTION_BOARD = (
-    CONTRACTS_ROOT / "maggiedash" / "execution-board.json"
-    if PACKAGED_CONTRACTS_ROOT.is_dir()
-    else REPO_ROOT / "docs" / "maggiedash-booking" / "EXECUTION-BOARD.json"
-)
+# The Booking delivery board is a maintainer document of the Maggie source
+# repository; the npm package does not ship it (config/release-privacy.json).
+EXECUTION_BOARD = REPO_ROOT / "docs" / "maggiedash-booking" / "EXECUTION-BOARD.json"
 
 
 def load_json(path: Path) -> dict:
@@ -57,6 +55,8 @@ def load_gate_json(path: Path, label: str) -> tuple[dict | None, str | None]:
 
 
 def load_execution_board(path: Path = EXECUTION_BOARD) -> dict:
+    if not path.is_file():
+        raise RuntimeError("the Booking delivery board lives in the Maggie source repository (docs/maggiedash-booking/EXECUTION-BOARD.json); pass --board PATH")
     board = load_json(path)
     if board.get("schemaVersion") != "maggiedash-booking-execution-board.v1":
         raise RuntimeError("unsupported Booking execution board schema")
@@ -260,6 +260,10 @@ def access_contract_checks(contract: dict) -> list[str]:
     return errors
 
 
+EMAIL_TEMPLATE_EVENTS_LEGACY = ["booking.confirmed", "booking.rescheduled", "booking.cancelled", "booking.reminder", "payment.action_required", "payment.refunded", "payment.no_show_fee", "package.purchase.confirmed", "package.purchase.refunded", "booking.waitlist.available"]
+EMAIL_TEMPLATE_EVENTS = EMAIL_TEMPLATE_EVENTS_LEGACY[:-1] + ["payment.late_refund_pending", "business.booking_cancelled", "business.booking_rescheduled", "business.late_payment_refund_required", "booking.waitlist.available"]
+
+
 def email_templates_contract_checks(contract: dict) -> list[str]:
     errors: list[str] = []
     properties = contract.get("properties") if isinstance(contract.get("properties"), dict) else {}
@@ -289,12 +293,13 @@ def email_templates_contract_checks(contract: dict) -> list[str]:
     if auth.get("passkeys") is not False: errors.append("passkeys must be disabled")
     if roles != ["owner", "admin", "manager"]: errors.append("roles must be owner, admin, manager")
     events = contract.get("events")
-    if not isinstance(events, list) or len(events) != 10: errors.append("exactly ten Booking email events are required")
     event_ids = [item.get("id") for item in events if isinstance(item, dict)] if isinstance(events, list) else []
-    expected_events = ["booking.confirmed", "booking.rescheduled", "booking.cancelled", "booking.reminder", "payment.action_required", "payment.refunded", "payment.no_show_fee", "package.purchase.confirmed", "package.purchase.refunded", "booking.waitlist.available"]
-    if event_ids != expected_events: errors.append("email event IDs are incomplete or out of order")
+    # MaggieDash <= 0.2.12 installs ship the ten-event contract; 0.2.13 adds the
+    # late-payment and business notices. Both are valid installed contracts.
+    if event_ids not in (EMAIL_TEMPLATE_EVENTS, EMAIL_TEMPLATE_EVENTS_LEGACY):
+        errors.append(f"email template events must be the {len(EMAIL_TEMPLATE_EVENTS)}-event list (or the {len(EMAIL_TEMPLATE_EVENTS_LEGACY)}-event list of MaggieDash 0.2.12 and earlier), in order")
     if len(event_ids) != len(set(event_ids)): errors.append("email event IDs must be unique")
-    allowed = {"customerName", "serviceName", "when", "locationName", "bookingId", "manageUrl", "bookingUrl", "reason", "actionUrl", "packageName", "amount", "expiresAt", "siteName", "arrivalNote"}
+    allowed = {"customerName", "serviceName", "when", "locationName", "bookingId", "manageUrl", "bookingUrl", "reason", "actionUrl", "packageName", "amount", "expiresAt", "siteName", "arrivalNote", "cancelledBy", "previousWhen"}
     declared_variables = contract.get("variables")
     event_variables = {variable for event in events if isinstance(event, dict) for variable in event.get("variables", []) if isinstance(variable, str)} if isinstance(events, list) else set()
     if declared_variables is not None and (not isinstance(declared_variables, list) or set(declared_variables) != event_variables or len(declared_variables) != len(set(declared_variables))):
@@ -656,9 +661,9 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
     stripe_webhook = has("STRIPE_WEBHOOK_SECRET")
     stripe_complete = stripe_secret and stripe_webhook
     stripe_partial = stripe_secret != stripe_webhook
-    stripe_key_help = "STRIPE_SECRET_KEY (or existing ORA alias ST_SECRECT_KEY)"
+    stripe_key_help = "STRIPE_SECRET_KEY (or the legacy alias ST_SECRECT_KEY)"
     stripe_detail = (
-        "Recognizes ORA's existing ST_SECRECT_KEY alias; prefer STRIPE_SECRET_KEY for new deployments. Verify the connection in Booking Overview."
+        "Recognizes the legacy ST_SECRECT_KEY alias; prefer STRIPE_SECRET_KEY for new deployments. Verify the connection in Booking Overview."
         if stripe_legacy_alias and stripe_complete
         else f"Both {stripe_key_help} and STRIPE_WEBHOOK_SECRET are required for online payments."
         if stripe_partial
@@ -867,7 +872,8 @@ def command_install(args: argparse.Namespace) -> int:
         return 2
     root = project_path(args)
     dash = Path(__file__).with_name("maggie_dash.py")
-    command = [sys.executable, str(dash), "install", "--project", str(root), "--host", args.host]
+    # Booking is an optional MaggieDash module: install the core and Booking.
+    command = [sys.executable, str(dash), "install", "--project", str(root), "--host", args.host, "--with", "booking"]
     if args.source:
         command.extend(["--source", args.source])
     if args.ref:
@@ -1445,6 +1451,12 @@ def parser() -> argparse.ArgumentParser:
 
 
 if __name__ == "__main__":
+    if sys.argv[1:2] == ["rules-vectors"]:
+        from maggie_booking_rules import main as rules_main
+        raise SystemExit(rules_main(sys.argv[2:]))
+    if sys.argv[1:2] == ["connect-qa"]:
+        from maggie_booking_connect_qa import main as connect_qa_main
+        raise SystemExit(connect_qa_main(sys.argv[2:]))
     try:
         arguments = parser().parse_args()
         raise SystemExit(arguments.func(arguments))

package/bundled-tools/clis/maggie_booking_connect_qa.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Test-mode Stripe Connect QA for a booking platform (``maggie booking connect-qa``).
+
+Without a test-mode connected account every Connect path (deposits on the
+business's account, saved cards, no-show fees, packages, memberships,
+refunds, card readers) can only be tested with simulated signed webhooks.
+This command prepares a real end-to-end test run without changing anything:
+
+- refuses live keys (``sk_live_``/``rk_live_``) and reports which variable
+  names are set (never values);
+- with ``--detect``, lists the platform's **test-mode** connected accounts
+  (read-only ``GET /v1/accounts``) and names one that can take charges, or
+  explains how to create one in test mode;
+- prints the ``stripe listen`` command that forwards both platform and Connect
+  events to the local webhook routes;
+- lists the payment cases to run, with Stripe's test cards and the reader
+  simulator, so a QA run records each outcome.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import sys
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+KEY_NAMES = ("STRIPE_SECRET_KEY", "STRIPE_API_KEY")
+WEBHOOK_SECRET_NAMES = ("STRIPE_CONNECT_WEBHOOK_SECRET", "STRIPE_WEBHOOK_SECRET")
+EVENTS = [
+    "checkout.session.completed", "checkout.session.expired", "payment_intent.succeeded", "payment_intent.payment_failed",
+    "setup_intent.succeeded", "charge.refunded", "charge.dispute.created", "customer.subscription.created",
+    "customer.subscription.updated", "customer.subscription.deleted", "invoice.paid", "invoice.payment_failed",
+    "terminal.reader.action_succeeded", "terminal.reader.action_failed", "account.updated",
+]
+CASES = [
+    {"id": "deposit", "do": "Book a deposit service and pay with 4242 4242 4242 4242", "expect": "booking confirmed only after the Connect webhook; payment row on the connected account; amount, currency and account checked"},
+    {"id": "strong-authentication", "do": "Pay with 4000 0025 0000 3155 and complete 3-D Secure", "expect": "confirmed after authentication; the return page polls instead of confirming"},
+    {"id": "declined", "do": "Pay with 4000 0000 0000 0002", "expect": "booking stays pending_payment, hold expires, slot freed"},
+    {"id": "late-payment", "do": "Let the hold expire, then complete the Checkout session", "expect": "reinstated if the time is free, otherwise refunded in full with a client e-mail (rule late_payment)"},
+    {"id": "saved-card-no-show", "do": "Save a card (SetupIntent), mark the booking no-show, charge the no-show fee off-session", "expect": "fee charged on the connected account with the saved payment method; 4000 0027 6000 3184 asks for authentication and must notify the client"},
+    {"id": "package", "do": "Buy a treatment package", "expect": "package credits issued once per payment; redeeming one reduces the balance"},
+    {"id": "membership", "do": "Start a monthly membership, pause it, resume it", "expect": "subscription on the connected account; credits only in billed months (rule membership_credits)"},
+    {"id": "refund", "do": "Refund in full and partly from the dashboard", "expect": "refund on the connected account; charge.refunded reconciles the booking payment"},
+    {"id": "card-reader", "do": "Register the simulated reader (registration code simulated-wpe), send a sale to it, present a test card", "expect": "payment recorded only when the PaymentIntent succeeds; reader cancel leaves the sale open"},
+    {"id": "dispute", "do": "Pay with 4000 0000 0000 0259", "expect": "dispute shown to the business; no automatic refund"},
+]
+
+
+def _env(env_file: Path | None) -> dict[str, str]:
+    values = dict(os.environ)
+    if env_file and env_file.is_file():
+        for line in env_file.read_text(encoding="utf-8", errors="replace").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                key, value = line.removeprefix("export ").split("=", 1)
+                values.setdefault(key.strip(), value.strip().strip("\"'"))
+    return values
+
+
+def list_accounts(key: str) -> dict:
+    token = base64.b64encode(f"{key}:".encode()).decode()
+    request = Request("https://api.stripe.com/v1/accounts?limit=20", headers={"Authorization": f"Basic {token}"})
+    try:
+        with urlopen(request, timeout=20) as response:  # noqa: S310 - fixed Stripe API host, GET only
+            return json.loads(response.read())
+    except HTTPError as error:
+        return {"error": f"Stripe answered {error.code}"}
+    except (URLError, OSError, ValueError) as error:
+        return {"error": str(error)[:120]}
+
+
+def connect_qa(env_file: Path | None, connect_url: str, platform_url: str | None, detect: bool, lister=list_accounts) -> dict:
+    values = _env(env_file)
+    errors: list[str] = []
+    warnings: list[str] = []
+    key_name = next((name for name in KEY_NAMES if values.get(name)), None)
+    key = values.get(key_name, "") if key_name else ""
+    if not key:
+        errors.append("no Stripe secret key found (STRIPE_SECRET_KEY); use the platform's test-mode key")
+    elif key.startswith(("sk_live_", "rk_live_")):
+        errors.append(f"{key_name} is a live key; Connect QA runs only in test mode — switch to the sk_test_ key")
+        key = ""
+    elif not key.startswith(("sk_test_", "rk_test_")):
+        warnings.append(f"{key_name} does not look like a Stripe test key")
+    secrets = {name: bool(values.get(name)) for name in WEBHOOK_SECRET_NAMES}
+    if not any(secrets.values()):
+        warnings.append("no webhook signing secret is set; copy the whsec_ value printed by `stripe listen` into the Connect webhook secret variable")
+    accounts = None
+    ready = None
+    if detect and key:
+        listing = lister(key)
+        if "error" in listing:
+            errors.append(f"could not list connected accounts: {listing['error']}")
+        else:
+            accounts = [{"id": a.get("id"), "chargesEnabled": bool(a.get("charges_enabled")), "detailsSubmitted": bool(a.get("details_submitted")), "country": a.get("country")} for a in listing.get("data", [])]
+            ready = next((a["id"] for a in accounts if a["chargesEnabled"]), None)
+            if not accounts:
+                warnings.append("no test-mode connected account yet: in the Stripe Dashboard (test mode) open Connect → Accounts → Create, complete onboarding with test data, then re-run with --detect")
+            elif not ready:
+                warnings.append("test connected accounts exist but none can take charges yet; finish onboarding with Stripe's test data")
+    listen = "stripe listen --forward-connect-to " + connect_url + (f" --forward-to {platform_url}" if platform_url else "") + " --events " + ",".join(EVENTS)
+    return {
+        "schemaVersion": "maggiedash-booking-connect-qa.v1",
+        "mode": "test",
+        "keyVariable": key_name,
+        "webhookSecrets": secrets,
+        "connectedAccounts": accounts,
+        "testAccount": ready,
+        "commands": [listen, "stripe trigger checkout.session.completed --stripe-account <acct_test_id>  # smoke the Connect route"],
+        "cases": CASES,
+        "status": "failed" if errors else ("warning" if warnings else "ready"),
+        "errors": errors,
+        "warnings": warnings,
+        "note": "read-only: nothing was created or charged; record each case's outcome with maggie qa record",
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie booking connect-qa", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--project", type=Path, default=Path("."))
+    parser.add_argument("--env-file", type=Path, help="default: <project>/.env")
+    parser.add_argument("--connect-webhook-url", default="http://localhost:4321/api/stripe/connect-events")
+    parser.add_argument("--platform-webhook-url", help="platform (non-Connect) webhook route, if separate")
+    parser.add_argument("--detect", action="store_true", help="read-only: list test-mode connected accounts")
+    args = parser.parse_args(argv)
+    report = connect_qa(args.env_file or args.project / ".env", args.connect_webhook_url, args.platform_webhook_url, args.detect)
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 1 if report["status"] == "failed" else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())