@topy-ai/maggie 0.7.38 → 0.7.41

package/bundled-tools/clis/maggie_booking.py

@@ -8,6 +8,7 @@ import json
 import os
 import re
 import secrets
+import shlex
 import shutil
 import subprocess
 import sys
@@ -200,7 +201,7 @@ def contract_checks(contract: dict) -> list[str]:
         if not isinstance(service_methods, dict) or set(service_methods) != set(endpoint_ids or []): errors.append("serviceMethods must map every endpoint exactly once")
         elif not all(isinstance(value, str) and value for value in service_methods.values()): errors.append("serviceMethods values must be non-empty strings")
         customer_methods = contract.get("customerServiceMethods")
-        if customer_methods != ["readPublicCatalog", "readPublicAvailability", "createCustomerHold", "startCustomerCheckout", "readCustomerPaymentReturn", "readCustomerManage", "cancelCustomerBooking", "rescheduleCustomerBooking", "joinCustomerWaitlist"]: errors.append("customerServiceMethods must declare the nine public customer methods")
+        if customer_methods != ["readPublicCatalog", "readPublicAvailability", "createCustomerHold", "startCustomerCheckout", "startCustomerPackageCheckout", "readCustomerPaymentReturn", "readCustomerPackagePaymentReturn", "readCustomerManage", "cancelCustomerBooking", "rescheduleCustomerBooking", "joinCustomerWaitlist"]: errors.append("customerServiceMethods must declare the eleven public customer methods")
     return errors
 
 
@@ -235,7 +236,17 @@ def access_contract_checks(contract: dict) -> list[str]:
     if auth.get("passkeys") is not False: errors.append("passkeys must be disabled")
     if auth.get("resendInvitation") is not True: errors.append("resendInvitation must be enabled")
     if roles != ["manager", "staff", "finance"]: errors.append("roles must be manager, staff, finance")
-    for permission in ("calendar.read", "bookings.manage", "payments.manage", "refunds.manage", "audit.read"):
+    expected_permissions = (
+        "calendar.read", "bookings.read", "bookings.manage", "customers.read",
+        "waitlist.read", "waitlist.manage", "catalog.read", "catalog.manage",
+        "packages.read", "packages.manage", "staff.read", "staff.manage",
+        "resources.read", "resources.manage", "schedule.read", "schedule.manage",
+        "locations.read", "locations.manage", "payments.read", "payments.manage",
+        "refunds.manage", "notifications.read", "notifications.manage",
+        "settings.read", "settings.manage", "reports.read", "audit.read",
+    )
+    if permissions != list(expected_permissions): errors.append("access permissions do not match the complete route capability registry")
+    for permission in expected_permissions:
         if permission not in permissions: errors.append(f"missing permission: {permission}")
     if endpoint_ids != ["booking.access.read", "booking.access.create", "booking.access.update", "booking.access.revoke"]: errors.append("access endpoint IDs are incomplete or out of order")
     expected = {"booking.access.read": "GET /access.json", "booking.access.create": "POST /access.json", "booking.access.update": "PATCH /access.json", "booking.access.revoke": "DELETE /access.json"}
@@ -273,12 +284,12 @@ 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) != 7: errors.append("exactly seven Booking email events are required")
+    if not isinstance(events, list) or len(events) != 9: errors.append("exactly nine 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", "booking.waitlist.available"]
+    expected_events = ["booking.confirmed", "booking.rescheduled", "booking.cancelled", "booking.reminder", "payment.action_required", "payment.refunded", "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")
     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", "siteName"}
+    allowed = {"customerName", "serviceName", "when", "locationName", "bookingId", "manageUrl", "bookingUrl", "reason", "actionUrl", "packageName", "amount", "expiresAt", "siteName"}
     for event in events if isinstance(events, list) else []:
         variables = event.get("variables") if isinstance(event, dict) else None
         if not isinstance(variables, list) or not variables: errors.append(f"{event.get('id', 'unknown')}: variables must be a non-empty list")
@@ -331,7 +342,7 @@ def customer_contract_checks(contract: dict) -> list[str]:
     if noindex is not True: errors.append("customer surface must be noindex")
     if properties == {} and response_policy.get("mutationPolicy") != "all-public-mutations-require-idempotency-key-and-replay-original-result": errors.append("customer mutationPolicy must require idempotent replay")
     if properties == {} and set(response_policy.get("holdInputPolicy", [])) != {"valid-email", "booking-update-consent"}: errors.append("customer holdInputPolicy must require valid email and booking-update-consent")
-    if len(endpoints) != 9: errors.append("customer surface must declare nine endpoints")
+    if len(endpoints) != 11: errors.append("customer surface must declare eleven endpoints")
     if len(ids) != len(set(ids)): errors.append("customer endpoint IDs must be unique")
     if not all(str(item).startswith("booking.public.") for item in ids): errors.append("customer endpoint IDs must use the booking.public namespace")
     for endpoint in endpoints:
@@ -630,7 +641,7 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
         setup_check("site", "Public site URL", ["PUBLIC_SITE_URL"], has("PUBLIC_SITE_URL"), detail="Used for login links, booking links, and email URLs."),
         setup_check("booking-token", "Public booking token secret", ["BOOKING_TOKEN_SECRET"], token_valid, detail="Must be at least 32 characters; used to sign public manage-booking links." if token_valid or not token_present else "The configured secret is too short; use at least 32 characters.", status_override="passed" if token_valid else "invalid" if token_present else None),
         setup_check("resend", "Resend email delivery", ["RESEND_API_KEY", "EMAIL_FROM|RESEND_FROM_EMAIL"], has("RESEND_API_KEY") and has_sender, detail="Required for password setup/reset, booking notifications, and reminders."),
-        setup_check("stripe", "Stripe online payments", ["STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET"], stripe_complete, required=False, detail="Required only for deposit/full online payment flows; webhook URL is /api/maggie/booking/webhooks/stripe." if not stripe_partial else "Both Stripe secret and webhook secret are required for online payments.", status_override="passed" if stripe_complete else "degraded" if stripe_partial else "optional"),
+        setup_check("stripe", "Stripe online payments", ["STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET"], stripe_complete, required=False, detail="Required only for deposit/full online payment flows; webhook URL is /api/maggie/booking/webhooks/stripe." if not stripe_partial and (stripe_secret or stripe_webhook) else "Both Stripe secret and webhook secret are required for online payments." if stripe_partial else "Optional at install: an owner or manager can connect Stripe from Booking Overview, or use the deployment secret store.", status_override="passed" if stripe_complete else "degraded" if stripe_partial else "optional"),
         {"id": "schema", "label": "Booking database schema", "status": "not-verified", "required": True, "detail": "The CLI does not connect to PostgreSQL. Apply the schema after backup, then verify with the host runtime checks."},
         {"id": "owner", "label": "First owner account", "status": "not-verified", "required": True, "detail": "Open /_maggie/register once the schema is applied. Registration closes after the first owner."},
         {"id": "worker", "label": "Resend worker schedule", "status": "not-verified", "required": True, "detail": "Run the installed worker from a single-flight scheduler; setup does not create a cron or systemd job."},
@@ -647,15 +658,19 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
     if "stripe" in degraded_config:
         next_steps.append("Configure both STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET before accepting online payments.")
     if missing_dependencies:
-        next_steps.append("Install missing host packages with the project package manager: maggie booking install --project . --confirm --install-dependencies")
-    if any(item["id"] == "schema" and item["status"] == "not-verified" for item in checks):
+        next_steps.append("For a new host, install missing packages and apply the schema together: maggie booking install --project . --confirm --ready")
+    if not missing_dependencies and any(item["id"] == "schema" and item["status"] == "not-verified" for item in checks):
         next_steps.append("After backup, run: maggie booking install --project . --confirm --bootstrap")
     if any(item["id"] == "owner" and item["status"] == "not-verified" for item in checks):
         next_steps.append("Open /_maggie/register and create the first owner, then sign in at /_maggie/login")
     if any(item["id"] == "worker" and item["status"] == "not-verified" for item in checks):
         next_steps.append("Configure a single-flight scheduler for: node scripts/maggie-booking-worker.mjs --write --confirm")
-    if not has("STRIPE_SECRET_KEY") or not has("STRIPE_WEBHOOK_SECRET"):
-        next_steps.append("If taking online payments, configure Stripe test keys and POST /api/maggie/booking/webhooks/stripe before live mode.")
+    if stripe_partial:
+        next_steps.append("Complete both Stripe deployment keys before accepting online payments; then POST /api/maggie/booking/webhooks/stripe and verify the connection.")
+    elif not stripe_complete:
+        next_steps.append("After signing in, an owner or manager can connect Stripe from Booking Overview; alternatively add both deployment keys, configure the webhook URL, and verify the connection.")
+    else:
+        next_steps.append("After signing in, open Booking Overview and run Verify Stripe connection; env-key presence alone is not connected state.")
     status = "needs-configuration" if missing_required else "configured-pending-verification"
     return {
         "status": status,
@@ -663,7 +678,7 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
         "checks": checks,
         "configuredKeys": sorted(key for key in sources if key in {"DATABASE_URL", "PUBLIC_SITE_URL", "BOOKING_TOKEN_SECRET", "RESEND_API_KEY", "EMAIL_FROM", "RESEND_FROM_EMAIL", "STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET"}),
         "verificationPending": verification_pending,
-        "paymentConfiguration": "online-payments" if has("STRIPE_SECRET_KEY") and has("STRIPE_WEBHOOK_SECRET") else "no-payment-or-incomplete-stripe",
+        "paymentConfiguration": "online-payments-pending-verification" if stripe_complete else "incomplete-deployment-stripe" if stripe_partial else "dashboard-or-host-secret-pending",
         "next": next_steps,
         "note": "Read-only checklist. It does not print secrets, connect to PostgreSQL, apply migrations, create an owner, configure Stripe, send email, or deploy.",
     }
@@ -714,10 +729,101 @@ def ensure_bootstrap_token_secret(root: Path) -> bool:
     return True
 
 
+def write_worker_schedule(root: Path, scheduler: str, *, force: bool = False) -> dict:
+    """Generate a host-owned single-flight schedule for the installed worker.
+
+    The CLI writes deployment artifacts only. It never enables a systemd unit,
+    edits the host crontab, starts a process, or prints environment values.
+    The host operator remains responsible for reviewing the unit, selecting an
+    unprivileged service user, and enabling it after migration/evidence gates.
+    """
+    if scheduler not in {"systemd", "cron"}:
+        raise RuntimeError("worker scheduler must be systemd or cron")
+    script = root / "scripts" / "maggie-booking-worker.mjs"
+    if not script.is_file():
+        raise RuntimeError(f"installed Booking worker is missing: {script}")
+    output_dir = root / "deploy"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    env_file = root / ".env"
+    worker_log = root / ".maggie" / "booking-worker.log"
+    worker_log.parent.mkdir(parents=True, exist_ok=True)
+    root_text = root.as_posix()
+    script_text = script.as_posix()
+    env_text = env_file.as_posix()
+    output: dict[str, str] = {}
+    if scheduler == "systemd":
+        service = output_dir / "maggie-booking-worker.service"
+        timer = output_dir / "maggie-booking-worker.timer"
+        service_text = f"""[Unit]
+Description=Maggie Booking worker and Resend outbox delivery
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+# Review and set an unprivileged deployment user before enabling this unit.
+WorkingDirectory={root_text}
+EnvironmentFile=-{env_text}
+ExecStart=/usr/bin/env node {script_text} --write --confirm
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths={root_text}/.maggie
+
+[Install]
+WantedBy=multi-user.target
+"""
+        timer_text = """[Unit]
+Description=Run Maggie Booking worker every minute
+
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=1min
+AccuracySec=10s
+Persistent=true
+Unit=maggie-booking-worker.service
+
+[Install]
+WantedBy=timers.target
+"""
+        for path, text in ((service, service_text), (timer, timer_text)):
+            if path.exists() and not force:
+                output[path.name] = "unchanged"
+                continue
+            path.write_text(text, encoding="utf-8")
+            output[path.name] = "written"
+    else:
+        cron = output_dir / "maggie-booking-worker.cron"
+        command = "cd {root} && {worker}".format(
+            root=shlex.quote(root_text),
+            worker=" ".join([
+                "/usr/bin/flock -n /tmp/maggie-booking-worker.lock",
+                "/usr/bin/env node",
+                shlex.quote(script_text),
+                "--write --confirm",
+            ]),
+        )
+        cron_text = f"""# Maggie Booking worker; install with the deploy user's crontab after review.
+# The worker performs its own PostgreSQL migration preflight and tenant lock.
+* * * * * {command} >> {shlex.quote(worker_log.as_posix())} 2>&1
+"""
+        if cron.exists() and not force:
+            output[cron.name] = "unchanged"
+        else:
+            cron.write_text(cron_text, encoding="utf-8")
+            output[cron.name] = "written"
+    return {"status": "generated", "scheduler": scheduler, "files": output, "note": "Review and enable the host scheduler after migration and release evidence; no service or crontab was changed."}
+
+
 def command_install(args: argparse.Namespace) -> int:
     """Install Booking, optionally adding missing host packages and schema."""
-    if (args.bootstrap or args.install_dependencies) and (args.dry_run or args.diff):
-        print("INSTALL_MUTATION_INCOMPATIBLE: --bootstrap and --install-dependencies cannot be combined with --dry-run or --diff.", file=sys.stderr)
+    schedule = getattr(args, "schedule", "none")
+    ready = bool(getattr(args, "ready", False))
+    install_dependencies = bool(getattr(args, "install_dependencies", False) or ready)
+    bootstrap = bool(getattr(args, "bootstrap", False) or ready)
+    if (bootstrap or install_dependencies or schedule != "none") and (args.dry_run or args.diff):
+        print("INSTALL_MUTATION_INCOMPATIBLE: --ready, --bootstrap, --install-dependencies, and --schedule cannot be combined with --dry-run or --diff.", file=sys.stderr)
         return 2
     if not args.dry_run and not args.diff and not args.confirm:
         print("CONFIRMATION_REQUIRED: add --confirm before installing Booking.", file=sys.stderr)
@@ -742,26 +848,47 @@ def command_install(args: argparse.Namespace) -> int:
     completed = subprocess.run(command, cwd=root, check=False)
     if completed.returncode != 0:
         return completed.returncode
-    if args.install_dependencies:
+    if install_dependencies:
         try:
             dependency_result = install_host_dependencies(root)
         except RuntimeError as error:
             print(f"DEPENDENCY_INSTALL_FAILED: {error}", file=sys.stderr)
             return 1
         print(json.dumps({"status": "host-dependencies", **dependency_result}, ensure_ascii=False))
-    if not args.bootstrap:
-        return 0
+    if bootstrap:
+        try:
+            ensure_bootstrap_token_secret(root)
+        except RuntimeError as error:
+            print(f"BOOTSTRAP_FAILED: {error}", file=sys.stderr)
+            return 1
+        schema_script = root / "scripts" / "maggie-booking-schema.mjs"
+        if not schema_script.is_file():
+            print(f"BOOTSTRAP_FAILED: installed host schema script is missing: {schema_script}", file=sys.stderr)
+            return 1
+        schema = subprocess.run(["node", str(schema_script), "--apply", "--confirm"], cwd=root, check=False)
+        if schema.returncode != 0:
+            return schema.returncode
+    if schedule != "none":
+        try:
+            print(json.dumps({"status": "worker-schedule", **write_worker_schedule(root, schedule, force=args.force)}, ensure_ascii=False))
+        except (OSError, RuntimeError) as error:
+            print(f"SCHEDULE_FAILED: {error}", file=sys.stderr)
+            return 1
+    return 0
+
+
+def command_worker_schedule(args: argparse.Namespace) -> int:
+    root = project_path(args)
+    if not args.confirm:
+        print("CONFIRMATION_REQUIRED: add --confirm before generating worker scheduler files.", file=sys.stderr)
+        return 2
     try:
-        ensure_bootstrap_token_secret(root)
-    except RuntimeError as error:
-        print(f"BOOTSTRAP_FAILED: {error}", file=sys.stderr)
-        return 1
-    schema_script = root / "scripts" / "maggie-booking-schema.mjs"
-    if not schema_script.is_file():
-        print(f"BOOTSTRAP_FAILED: installed host schema script is missing: {schema_script}", file=sys.stderr)
+        result = write_worker_schedule(root, args.scheduler, force=args.force)
+    except (OSError, RuntimeError) as error:
+        print(f"SCHEDULE_FAILED: {error}", file=sys.stderr)
         return 1
-    schema = subprocess.run(["node", str(schema_script), "--apply", "--confirm"], cwd=root, check=False)
-    return schema.returncode
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
 
 
 def command_inspect(args: argparse.Namespace) -> int:
@@ -1073,8 +1200,16 @@ def parser() -> argparse.ArgumentParser:
     install.add_argument("--existing-dir")
     install.add_argument("--install-dependencies", action="store_true", help="add missing Astro Booking packages with the host package manager")
     install.add_argument("--bootstrap", action="store_true", help="apply the installed host Booking schema after installation")
+    install.add_argument("--ready", action="store_true", help="install missing host packages and apply the Booking schema after installation")
+    install.add_argument("--schedule", choices=["none", "systemd", "cron"], default="none", help="generate a reviewed worker scheduler artifact after installation")
     install.add_argument("--confirm", action="store_true")
     install.set_defaults(func=command_install)
+    worker_schedule = sub.add_parser("worker-schedule", help="generate a reviewed systemd or cron Booking worker schedule")
+    worker_schedule.add_argument("--project", default=".")
+    worker_schedule.add_argument("--scheduler", choices=["systemd", "cron"], required=True)
+    worker_schedule.add_argument("--force", action="store_true")
+    worker_schedule.add_argument("--confirm", action="store_true")
+    worker_schedule.set_defaults(func=command_worker_schedule)
     contract = sub.add_parser("contract", help="validate the provider-neutral Booking contract")
     contract.add_argument("--contract", default=str(DEFAULT_CONTRACT))
     contract.set_defaults(func=command_contract)

package/bundled-tools/clis/maggie_browser_audit.py

@@ -13,6 +13,98 @@ from browser_behavior import validate_samples
 from localization_runner import checkpoint
 
 
+INTERACTION_ACTIONS = {
+    "click", "fill", "type", "select", "press", "wait",
+    "assert-visible", "assert-enabled", "assert-disabled", "assert-checked",
+    "assert-editable", "assert-text", "assert-style", "assert-no-request",
+}
+
+
+def load_interactions(path: Path | None) -> list[dict]:
+    if not path:
+        return []
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict) or value.get("schemaVersion") != "maggie-browser-interactions.v1":
+        raise ValueError("interaction manifest schemaVersion must be maggie-browser-interactions.v1")
+    steps = value.get("steps")
+    if not isinstance(steps, list) or not steps:
+        raise ValueError("interaction manifest steps must be a non-empty array")
+    for step in steps:
+        if not isinstance(step, dict) or step.get("action") not in INTERACTION_ACTIONS:
+            raise ValueError("each interaction step must use a supported action")
+        if step.get("action") not in {"wait", "press", "assert-no-request"} and not str(step.get("selector") or "").strip():
+            raise ValueError("interaction step selector is required")
+    return steps
+
+
+def js_value(call, expression: str):
+    raw = call("js", expression).strip()
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return raw.strip('"')
+
+
+def resource_urls(call) -> set[str]:
+    value = js_value(call, "JSON.stringify(performance.getEntriesByType('resource').map(entry => entry.name))")
+    return set(value if isinstance(value, list) else [])
+
+
+def run_interactions(call, steps: list[dict]) -> list[dict]:
+    baseline = resource_urls(call)
+    evidence = []
+    for step in steps:
+        action = step["action"]
+        selector = str(step.get("selector") or "")
+        record = {"id": str(step.get("id") or f"step-{len(evidence) + 1}"), "action": action, "selector": selector, "status": "passed"}
+        try:
+            if action == "click":
+                call("click", selector)
+            elif action == "fill":
+                call("fill", selector, str(step.get("value") or ""))
+            elif action == "type":
+                call("click", selector)
+                call("type", str(step.get("text") or ""))
+            elif action == "select":
+                call("select", selector, str(step.get("value") or ""))
+            elif action == "press":
+                call("press", str(step.get("key") or "Enter"))
+            elif action == "wait":
+                call("wait", str(step.get("target") or "--load"))
+            elif action.startswith("assert-") and action in {"assert-visible", "assert-enabled", "assert-disabled", "assert-checked", "assert-editable"}:
+                call("is", action.removeprefix("assert-"), selector)
+            elif action == "assert-text":
+                expected = str(step.get("text") or "")
+                expression = f"(() => {{ const node = document.querySelector({json.dumps(selector)}); return Boolean(node && node.textContent.includes({json.dumps(expected)})); }})()"
+                if js_value(call, expression) is not True:
+                    raise ValueError("text assertion failed")
+            elif action == "assert-style":
+                prop = str(step.get("property") or "")
+                expected = str(step.get("value") or "")
+                if not prop:
+                    raise ValueError("style assertion property is required")
+                expression = f"(() => {{ const node = document.querySelector({json.dumps(selector)}); return node ? getComputedStyle(node)[{json.dumps(prop)}] : null; }})()"
+                actual = js_value(call, expression)
+                if actual != expected:
+                    raise ValueError("style assertion failed")
+            elif action == "assert-no-request":
+                forbidden = str(step.get("origin") or step.get("url") or "")
+                if not forbidden:
+                    raise ValueError("request assertion origin is required")
+                new_urls = sorted(url for url in resource_urls(call) - baseline if forbidden in url)
+                if new_urls:
+                    raise ValueError("third-party request assertion failed")
+            else:
+                raise ValueError("unsupported interaction action")
+        except (OSError, ValueError, subprocess.TimeoutExpired) as error:
+            record["status"] = "failed"
+            record["error"] = str(error)
+            evidence.append(record)
+            break
+        evidence.append(record)
+    return evidence
+
+
 def audit(args):
     if urlparse(args.url).scheme not in {"http", "https", "file"}:
         raise ValueError("URL must use http, https or file")
@@ -20,13 +112,15 @@ def audit(args):
         raise ValueError("at least one --required selector is necessary")
     output = args.output.resolve()
     output.mkdir(parents=True, exist_ok=True)
+    interactions = load_interactions(args.interactions)
     def call(*command):
         result = subprocess.run([str(args.browse), *command], capture_output=True, text=True, timeout=45)
         if result.returncode:
             raise ValueError("browser command failed: " + command[0])
         return result.stdout
     report = {"schemaVersion": "maggie-browser-audit.v1", "url": args.url,
-              "passed": False, "viewports": [], "evidence": "browser-captured"}
+              "passed": False, "viewports": [], "evidence": "browser-captured",
+              "interactionManifest": str(args.interactions.resolve()) if args.interactions else None}
     try:
         for index, viewport in enumerate(args.viewport or ["390x844", "768x1024", "1440x900"]):
             width, height = [int(value) for value in viewport.split("x")]
@@ -36,6 +130,7 @@ def audit(args):
             call("goto", args.url)
             selectors = list(dict.fromkeys(args.required + args.sticky))
             call("js", "window.__maggieAuditSelectors=" + json.dumps(selectors))
+            interaction_evidence = run_interactions(call, interactions) if interactions else []
             samples = []
             for step, fraction in enumerate([0, 0.5, 0.9]):
                 call("js", f"window.scrollTo(0, (document.documentElement.scrollHeight-innerHeight)*{fraction})")
@@ -50,8 +145,8 @@ def audit(args):
                 raise ValueError("browser did not create screenshot")
             finding = validate_samples(samples, args.required, args.sticky)
             report["viewports"].append({"viewport": viewport, "samples": samples,
-                "screenshot": str(screenshot), **finding})
-        report["passed"] = all(item["passed"] for item in report["viewports"])
+                "screenshot": str(screenshot), "interactionEvidence": interaction_evidence, **finding})
+        report["passed"] = all(item["passed"] and all(step["status"] == "passed" for step in item.get("interactionEvidence", [])) for item in report["viewports"])
     finally:
         checkpoint(output / "report.json", report)
     print(json.dumps(report, indent=2))
@@ -66,6 +161,7 @@ def main():
     parser.add_argument("--viewport", action="append")
     parser.add_argument("--required", action="append", default=[])
     parser.add_argument("--sticky", action="append", default=[])
+    parser.add_argument("--interactions", type=Path, help="declarative interaction/assertion manifest")
     args = parser.parse_args()
     try:
         return audit(args)

package/bundled-tools/clis/maggie_clone.py

@@ -316,6 +316,48 @@ def command_verify(args):
     return 0
 
 
+def command_interactions(args):
+    """Replay the shared browser-audit manifest for every clone target/viewport."""
+    root, manifest = read_manifest(args.project.resolve(), args.run_id)
+    interaction_path = args.interactions.resolve()
+    try:
+        interaction_manifest = json.loads(interaction_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"cannot read interaction manifest: {error}") from error
+    if interaction_manifest.get("schemaVersion") != "maggie-browser-interactions.v1" or not isinstance(interaction_manifest.get("steps"), list) or not interaction_manifest["steps"]:
+        raise ValueError("interaction manifest must be a non-empty maggie-browser-interactions.v1 document")
+    evidence_root = root / "interactions"
+    evidence_root.mkdir(parents=True, exist_ok=True)
+    reports = []
+    states = []
+    audit_cli = Path(__file__).with_name("maggie_browser_audit.py")
+    for target in manifest["targets"]:
+        output = evidence_root / target["page_key"]
+        selectors = {str(step.get("selector")) for step in interaction_manifest["steps"] if step.get("selector")}
+        command = [sys.executable, str(audit_cli), target.get("capture_url", target["source_url"]), "--browse", str(args.browse), "--output", str(output), "--interactions", str(interaction_path), "--required", "body"]
+        for selector in sorted(selectors):
+            command.extend(["--required", selector])
+        for viewport in VIEWPORTS:
+            command.extend(["--viewport", f"{VIEWPORTS[viewport][0]}x{VIEWPORTS[viewport][1]}"])
+        completed = subprocess.run(command, capture_output=True, text=True, check=False)
+        report_path = output / "report.json"
+        reports.append({"pageKey": target["page_key"], "status": "passed" if completed.returncode == 0 else "failed", "report": str(report_path), "stderr": "browser audit failed" if completed.returncode else None})
+        try:
+            audit_report = json.loads(report_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            audit_report = {}
+        for viewport, viewport_report in zip(("desktop", "tablet", "mobile"), audit_report.get("viewports") or []):
+            for step in interaction_manifest["steps"]:
+                step_evidence = next((item for item in viewport_report.get("interactionEvidence", []) if item.get("id") == step.get("id")), {})
+                states.append({"viewport": viewport, "stepId": step["id"], "status": step_evidence.get("status", "failed"), "screenshot": viewport_report.get("screenshot"), "error": step_evidence.get("error")})
+    evidence = {"schemaVersion": "maggie-clone-interaction-state.v1", "sourceRunId": manifest["run_id"], "interactionManifest": str(interaction_path), "viewports": list(VIEWPORTS), "states": states, "redacted": True, "reports": reports, "passed": bool(reports) and bool(states) and all(item["status"] == "passed" for item in reports) and all(item["status"] == "passed" for item in states)}
+    save_json(evidence_root / "evidence.json", evidence)
+    manifest["interactionEvidence"] = str(evidence_root / "evidence.json")
+    save_json(root / "manifest.json", manifest)
+    print(json.dumps(evidence, indent=2, ensure_ascii=False))
+    return 0 if evidence["passed"] else 1
+
+
 def command_status(args):
     root = run_root(args.project.resolve(), args.run_id)
     manifest_path = root / "manifest.json"
@@ -373,13 +415,16 @@ def main():
     status_parser.add_argument("--project", type=Path, default=Path.cwd())
     status_parser.add_argument("--run-id", required=True)
     status_parser.set_defaults(func=command_status)
-    commands = {"init": command_init, "capture": command_capture, "extract": command_extract, "assets": command_assets, "compare": command_compare, "verify": command_verify}
+    commands = {"init": command_init, "capture": command_capture, "extract": command_extract, "assets": command_assets, "compare": command_compare, "verify": command_verify, "interactions": command_interactions}
     for name, func in commands.items():
         cmd = sub.add_parser(name); cmd.add_argument("--project", type=Path, default=Path.cwd()); cmd.add_argument("--run-id", required=True); cmd.add_argument("--force", action="store_true")
         if name == "init": cmd.add_argument("urls", nargs="+")
         if name == "assets": cmd.add_argument("--max-bytes", type=int, default=20_000_000)
         if name == "compare": cmd.add_argument("--local-url", required=True)
         if name == "verify": cmd.add_argument("--allow-uncompared", action="store_true")
+        if name == "interactions":
+            cmd.add_argument("--browse", type=Path, required=True)
+            cmd.add_argument("--interactions", type=Path, required=True, help="shared maggie-browser-interactions.v1 manifest")
         cmd.set_defaults(func=func)
     args = parser.parse_args()
     try: return int(args.func(args) or 0)