@topy-ai/maggie 0.7.35 → 0.7.37

package/bundled-tools/clis/maggie_dash.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import shutil
 import subprocess
 import sys
@@ -145,9 +146,131 @@ def manifest_root_file_pairs(source: Path, manifest: dict[str, object], root: Pa
     return pairs
 
 
-def command_install_diff(source: Path, manifest: dict[str, object], target: Path, compare_dir: Path | None, force: bool) -> dict[str, object]:
+def manifest_workspace_file_pairs(source: Path, manifest: dict[str, object], root: Path) -> list[tuple[Path, Path, Path]]:
+    """Return additional installable workspaces such as ./_maggie/booking."""
+    pairs: list[tuple[Path, Path, Path]] = []
+    for item in manifest.get("workspaces", []):
+        if not isinstance(item, dict):
+            raise RuntimeError("MaggieDash workspaces entries must be objects")
+        source_relative = Path(str(item.get("source", "")))
+        target_relative = Path(str(item.get("target", "")))
+        if not source_relative.parts or not target_relative.parts:
+            raise RuntimeError("MaggieDash workspaces entries require source and target")
+        if source_relative.is_absolute() or target_relative.is_absolute() or ".." in source_relative.parts or ".." in target_relative.parts:
+            raise RuntimeError("unsafe MaggieDash workspace path")
+        source_item = source / source_relative
+        if not source_item.is_dir():
+            raise RuntimeError(f"MaggieDash workspace source is missing: {source_relative}")
+        for path in sorted(source_item.rglob("*")):
+            if path.is_file():
+                child = path.relative_to(source_item)
+                pairs.append((path, root / target_relative / child, source_relative / child))
+    return pairs
+
+
+def detect_host_framework(root: Path, requested: str) -> str | None:
+    """Resolve the optional host scaffold without guessing unsupported apps."""
+    if requested == "none":
+        return None
+    if requested != "auto":
+        return requested
+    package = root / "package.json"
+    try:
+        value = json.loads(package.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        value = {}
+    dependencies = set((value.get("dependencies") or {})) | set((value.get("devDependencies") or {}))
+    if "astro" in dependencies or any(root.glob("src/**/*.astro")):
+        return "astro"
+    return None
+
+
+ASTRO_MIDDLEWARE_MARKER = "maggie-auto-rewrite-v1"
+
+
+def merge_astro_middleware(path: Path) -> dict[str, object]:
+    """Add the stable Maggie paths to an existing conventional Astro middleware.
+
+    The installer must preserve host-owned auth/redirect logic. This narrow
+    merge only handles the common `onRequest = defineMiddleware((context,
+    next) => { ... })` shape and is idempotent. Unknown middleware shapes are
+    reported to the caller instead of being rewritten heuristically.
+    """
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError as error:
+        return {"status": "manual", "reason": f"could not read {path}: {error}"}
+    if ASTRO_MIDDLEWARE_MARKER in content:
+        return {"status": "unchanged", "reason": "Maggie rewrite block already present"}
+    required_patterns = ("/_maggie/booking", "/_maggie/login", "/_maggie/register", "/_maggie/reset-password")
+    if all(pattern in content for pattern in required_patterns) and "context.rewrite" in content:
+        return {"status": "unchanged", "reason": "existing middleware already exposes Maggie paths"}
+    match = re.search(
+        r"export\s+const\s+onRequest\s*=\s*defineMiddleware\(\s*\(\s*context\s*,\s*next\s*\)\s*=>\s*\{",
+        content,
+    )
+    if not match:
+        return {"status": "manual", "reason": "middleware is not the supported defineMiddleware((context, next) => {}) shape"}
+    block = r'''
+  // maggie-auto-rewrite-v1: generated by `maggie booking install`; keep host auth below.
+  const maggieRewrites: Array<[RegExp, (path: string) => string]> = [
+    [/^\/_maggie\/login\/?$/, () => "/maggie/login"],
+    [/^\/_maggie\/register\/?$/, () => "/maggie/register"],
+    [/^\/_maggie\/reset-password\/?$/, () => "/maggie/reset-password"],
+    [/^\/_maggie\/booking\/book\/?$/, () => "/maggie/booking/book"],
+    [/^\/_maggie\/booking(\/.*)?$/, (path) => "/maggie/booking" + path.replace(/^\/_maggie\/booking/, "")],
+  ];
+  for (const [pattern, target] of maggieRewrites) {
+    if (pattern.test(context.url.pathname)) {
+      const destination = new URL(target(context.url.pathname), context.url);
+      destination.search = context.url.search;
+      return context.rewrite(destination.pathname + destination.search);
+    }
+  }
+'''
+    merged = content[:match.end()] + block + content[match.end():]
+    try:
+        path.write_text(merged, encoding="utf-8")
+    except OSError as error:
+        return {"status": "manual", "reason": f"could not update {path}: {error}"}
+    return {"status": "updated", "reason": "inserted idempotent Maggie rewrite block"}
+
+
+def manifest_host_file_pairs(source: Path, manifest: dict[str, object], root: Path, framework: str | None) -> list[tuple[Path, Path, Path]]:
+    """Return non-destructive host files for a declared framework adapter."""
+    if not framework:
+        return []
+    bootstrap = manifest.get("hostBootstrap", {})
+    if not isinstance(bootstrap, dict):
+        return []
+    spec = bootstrap.get(framework)
+    if not isinstance(spec, dict):
+        raise RuntimeError(
+            f"MaggieDash distribution at {source} does not provide a {framework} host bootstrap; "
+            f"release a source with manifest.hostBootstrap.{framework} or pass --source to a released checkout"
+        )
+    source_relative = Path(str(spec.get("source", "")))
+    target_relative = Path(str(spec.get("target", ".")))
+    if not source_relative.parts or source_relative.is_absolute() or ".." in source_relative.parts:
+        raise RuntimeError("unsafe MaggieDash host bootstrap source")
+    if target_relative.as_posix() not in {".", ""} and (target_relative.is_absolute() or ".." in target_relative.parts):
+        raise RuntimeError("unsafe MaggieDash host bootstrap target")
+    source_item = source / source_relative
+    if not source_item.is_dir():
+        raise RuntimeError(f"MaggieDash host bootstrap source is missing: {source_relative}")
+    pairs: list[tuple[Path, Path, Path]] = []
+    for path in sorted(source_item.rglob("*")):
+        if path.is_file():
+            child = path.relative_to(source_item)
+            pairs.append((path, root / target_relative / child, source_relative / child))
+    return pairs
+
+
+def command_install_diff(source: Path, manifest: dict[str, object], target: Path, compare_dir: Path | None, force: bool, host_pairs: list[tuple[Path, Path, Path]] | None = None, host_framework: str | None = None) -> dict[str, object]:
     pairs = manifest_file_pairs(source, manifest, target)
     root_pairs = manifest_root_file_pairs(source, manifest, target.parents[1])
+    workspace_pairs = manifest_workspace_file_pairs(source, manifest, target.parents[1])
+    host_pairs = host_pairs or []
     files: list[dict[str, str]] = []
     source_relative = {relative for _, _, relative in pairs}
     for source_file, destination, relative in pairs:
@@ -172,6 +295,24 @@ def command_install_diff(source: Path, manifest: dict[str, object], target: Path
         else:
             action = "update" if force else "preserve"
         files.append({"path": str(relative), "action": action, "comparePath": str(compare_file)})
+    for source_file, destination, relative in workspace_pairs:
+        compare_file = destination
+        if not compare_file.exists():
+            action = "add"
+        elif compare_file.read_bytes() == source_file.read_bytes():
+            action = "unchanged"
+        else:
+            action = "update" if force else "preserve"
+        files.append({"path": str(relative), "action": action, "comparePath": str(compare_file)})
+    for source_file, destination, relative in host_pairs:
+        compare_file = destination
+        if not compare_file.exists():
+            action = "add"
+        elif compare_file.read_bytes() == source_file.read_bytes():
+            action = "unchanged"
+        else:
+            action = "update" if force else "preserve"
+        files.append({"path": f"host/{host_framework}/{relative}", "action": action, "comparePath": str(compare_file)})
     if compare_dir and compare_dir.exists():
         for existing in sorted(compare_dir.rglob("*")):
             if not existing.is_file():
@@ -183,13 +324,14 @@ def command_install_diff(source: Path, manifest: dict[str, object], target: Path
     summary: dict[str, int] = {}
     for item in files:
         summary[item["action"]] = summary.get(item["action"], 0) + 1
-    return {"status": "dry-run", "version": manifest.get("version"), "target": str(target), "compareDir": str(compare_dir) if compare_dir else None, "summary": summary, "files": files}
+    return {"status": "dry-run", "version": manifest.get("version"), "target": str(target), "hostFramework": host_framework, "compareDir": str(compare_dir) if compare_dir else None, "summary": summary, "files": files}
 
 
 def command_install(args: argparse.Namespace) -> int:
     if not args.dry_run and not args.diff:
         require_confirm(args)
     root = project_root(args)
+    host_framework = detect_host_framework(root, args.host)
     source_value = args.source or os.environ.get("MAGGIE_DASH_SOURCE") or DEFAULT_DASH_SOURCE
     ref = args.ref
     target_relative = Path(args.target)
@@ -222,6 +364,7 @@ def command_install(args: argparse.Namespace) -> int:
             raise RuntimeError("unsupported MaggieDash distribution schema")
         if manifest.get("target") != "_maggie/admin" and args.target == "_maggie/admin":
             raise RuntimeError("MaggieDash manifest target is not ./_maggie/admin")
+        host_pairs = manifest_host_file_pairs(source, manifest, root, host_framework)
         compare_dir = None
         if args.existing_dir:
             compare_dir = Path(args.existing_dir).expanduser()
@@ -229,7 +372,7 @@ def command_install(args: argparse.Namespace) -> int:
                 compare_dir = root / compare_dir
             compare_dir = compare_dir.resolve()
         if args.dry_run or args.diff:
-            emit(command_install_diff(source, manifest, target, compare_dir, args.force))
+            emit(command_install_diff(source, manifest, target, compare_dir, args.force, host_pairs, host_framework))
             return 0
         installed: list[str] = []
         preserved: list[str] = []
@@ -264,6 +407,32 @@ def command_install(args: argparse.Namespace) -> int:
                 destination.parent.mkdir(parents=True, exist_ok=True)
                 shutil.copy2(source_file, destination)
                 installed.append(str(destination))
+        for source_file, destination, _ in manifest_workspace_file_pairs(source, manifest, root):
+            if destination.exists() and not args.force:
+                preserved.append(str(destination))
+            else:
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source_file, destination)
+                installed.append(str(destination))
+        host_installed: list[str] = []
+        host_preserved: list[str] = []
+        host_updated: list[str] = []
+        host_warnings: list[str] = []
+        for source_file, destination, _ in host_pairs:
+            if destination.exists() and not args.force:
+                host_preserved.append(str(destination))
+            else:
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source_file, destination)
+                host_installed.append(str(destination))
+        if host_framework == "astro":
+            middleware = root / "src" / "middleware.ts"
+            if middleware.exists():
+                merge_result = merge_astro_middleware(middleware)
+                if merge_result.get("status") == "updated":
+                    host_updated.append(str(middleware))
+                elif merge_result.get("status") == "manual":
+                    host_warnings.append(str(merge_result.get("reason")))
         state = {
             "schemaVersion": "maggiedash-install.v1",
             "status": "installed",
@@ -274,13 +443,19 @@ def command_install(args: argparse.Namespace) -> int:
             "target": str(target),
             "installed": sorted(set(installed)),
             "preserved": sorted(set(preserved)),
+            "hostFramework": host_framework,
+            "hostBootstrap": "installed" if host_framework else "skipped",
+            "hostInstalled": sorted(set(host_installed)),
+            "hostPreserved": sorted(set(host_preserved)),
+            "hostUpdated": sorted(set(host_updated)),
+            "hostWarnings": sorted(set(host_warnings)),
             "updatedAt": utc_now(),
         }
         state_path = root / ".maggie" / "dash-install.json"
         state_path.parent.mkdir(parents=True, exist_ok=True)
         state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-        emit({"status": "installed", "version": manifest.get("version"), "target": str(target), "installed": len(set(installed)), "preserved": len(set(preserved)), "state": str(state_path)})
-        return 0
+        emit({"status": "needs-attention" if host_warnings else "installed", "version": manifest.get("version"), "target": str(target), "hostFramework": host_framework, "hostInstalled": len(set(host_installed)), "hostPreserved": len(set(host_preserved)), "hostUpdated": len(set(host_updated)), "hostWarnings": host_warnings, "installed": len(set(installed)), "preserved": len(set(preserved)), "state": str(state_path)})
+        return 1 if host_warnings else 0
     finally:
         if temporary is not None:
             temporary.cleanup()
@@ -630,6 +805,7 @@ def parser() -> argparse.ArgumentParser:
     install.add_argument("--source", help="local checkout or Git URL; defaults to MaggieDash repository")
     install.add_argument("--ref", default="main", help="Git ref when installing from a remote source")
     install.add_argument("--target", default="_maggie/admin", help="installation target relative to the project")
+    install.add_argument("--host", choices=["auto", "astro", "none"], default="auto", help="install the matching non-destructive host scaffold (default: auto-detect Astro)")
     install.add_argument("--force", action="store_true", help="replace existing dashboard files")
     install.add_argument("--dry-run", action="store_true", help="show the install plan without writing files")
     install.add_argument("--diff", action="store_true", help="show the install plan and compare with an existing workspace")

package/bundled-tools/clis/maggie_release.py

@@ -320,6 +320,29 @@ def editorial_gate(project: Path) -> dict:
     }
 
 
+def social_card_gate(project: Path) -> dict:
+    """Include the per-page social-card audit whenever a manifest is present."""
+    candidates = (
+        (project / "docs" / "social-cards-pages.json", "--pages-file"),
+        (project / ".maggie" / "social-cards-pages.json", "--pages-file"),
+        (project / "docs" / "public-urls.json", "--urls-file"),
+        (project / ".maggie" / "public-urls.json", "--urls-file"),
+    )
+    candidate = next(((path, flag) for path, flag in candidates if path.is_file()), None)
+    if candidate is None:
+        return {
+            "name": "social-card-audit",
+            "passed": True,
+            "exitCode": 0,
+            "result": {"passed": True, "state": "not-configured", "reason": "add docs/social-cards-pages.json or docs/public-urls.json to enable the release-path audit"},
+            "stderr": "",
+        }
+    path, flag = candidate
+    result = run_gate("social-card-audit", [sys.executable, str(ROOT / "maggie_social_cards.py"), "audit", flag, str(path)], project)
+    result["result"]["manifest"] = str(path.relative_to(project))
+    return result
+
+
 def runtime_smoke(base_url: str) -> dict:
     """Check basic public, admin redirect, and unknown-route behaviour."""
     base = base_url.rstrip("/") + "/"
@@ -366,6 +389,7 @@ def main() -> int:
     gates.append(changed_surface_gate(project))
     gates.append(qa_gate(project, args.environment, args.base_url))
     gates.append(build_gate(project))
+    gates.append(social_card_gate(project))
     for name, command in build_gates(project, args.environment, args.target, not args.skip_compatibility):
         gates.append(run_gate(name, command, project))
     if args.analytics_release_gate:

package/bundled-tools/clis/maggie_service_booking.py

@@ -7,6 +7,7 @@ import xml.etree.ElementTree as ET
 from datetime import datetime, timezone
 from html.parser import HTMLParser
 from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 from urllib.parse import quote, urljoin, urlsplit, urlparse
 from urllib.request import Request, urlopen
 
@@ -20,6 +21,39 @@ DURATION = re.compile(r"(\d{2,3})\s*(?:min|mins|minutes?)", re.I)
 SUPPLY_STATES = {"live", "withdrawn"}
 DISPLAY_STATES = {"published", "hidden", "retired"}
 
+
+def parse_booking_time(value, venue_timezone=None, venue_time_fold=None):
+    """Parse an appointment time using venue wall-clock rules, not server TZ."""
+    raw = str(value or "").strip()
+    parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        if not venue_timezone:
+            raise ValueError("venueTimezone is required for a timezone-naive booking time")
+        try:
+            zone = ZoneInfo(str(venue_timezone))
+        except ZoneInfoNotFoundError as exc:
+            raise ValueError("venueTimezone is not an installed IANA timezone") from exc
+        candidates = []
+        for fold in (0, 1):
+            candidate = parsed.replace(tzinfo=zone, fold=fold)
+            round_trip = candidate.astimezone(timezone.utc).astimezone(zone).replace(tzinfo=None)
+            if round_trip == parsed:
+                candidates.append(candidate)
+        if not candidates:
+            raise ValueError("venue wall-clock time does not exist because of a DST transition")
+        if len({candidate.utcoffset() for candidate in candidates}) > 1:
+            if venue_time_fold not in (0, 1):
+                raise ValueError("venueTimeFold 0 or 1 is required for an ambiguous DST time")
+            parsed = parsed.replace(tzinfo=zone, fold=venue_time_fold)
+        else:
+            parsed = candidates[0]
+    elif venue_timezone:
+        try:
+            parsed = parsed.astimezone(ZoneInfo(str(venue_timezone)))
+        except ZoneInfoNotFoundError as exc:
+            raise ValueError("venueTimezone is not an installed IANA timezone") from exc
+    return parsed
+
 def slug(value):
     value = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
     return value or "service"
@@ -1081,8 +1115,10 @@ def cmd_variant_audit(args):
         if typ=="event" and not v.get("eventId"): errors.append(f"{prefix}: eventId is required")
         if typ=="promotion" and not v.get("promotionId"): errors.append(f"{prefix}: promotionId is required")
         if typ in {"holiday","seasonal","event","promotion"}:
-            try: start=datetime.fromisoformat(str(v.get("startsAt","")).replace("Z","+00:00")); end=datetime.fromisoformat(str(v.get("endsAt","")).replace("Z","+00:00"))
-            except ValueError: errors.append(f"{prefix}: startsAt and endsAt are required ISO timestamps"); start=end=None
+            venue_timezone = v.get("venueTimezone") or (payload.get("venueTimezone") if isinstance(payload, dict) else None)
+            fold = v.get("venueTimeFold") if "venueTimeFold" in v else (payload.get("venueTimeFold") if isinstance(payload, dict) else None)
+            try: start=parse_booking_time(v.get("startsAt"), venue_timezone, fold); end=parse_booking_time(v.get("endsAt"), venue_timezone, fold)
+            except ValueError as exc: errors.append(f"{prefix}: startsAt and endsAt require venue wall-clock timezone ({exc})"); start=end=None
             if start and end and end<=start: errors.append(f"{prefix}: endsAt must be after startsAt")
             if end and end<=as_of and v.get("indexable") is True: errors.append(f"{prefix}: expired variant cannot be indexable")
         indexable=v.get("indexable") is True; noindex=v.get("noIndex") is True

package/bundled-tools/clis/site_audit.py

@@ -26,7 +26,10 @@ def stable_structure_reference(key: str, value: str) -> str:
     path = parsed.path
     if not re.search(r"\.(?:css|js|mjs|png|jpe?g|gif|webp|avif|svg|ico|woff2?|ttf|otf)$", path, re.I):
         return value
-    path = re.sub(r"(?:[-_.])[0-9a-f]{8,64}(?=\.[^.]+$)", "-asset", path, flags=re.I)
+    # Vite/Astro and similar bundlers also emit base64url-safe digests such as
+    # ``SiteLayout.Bdp0itNn.css``. Restrict this to a digest-looking token
+    # immediately before a known asset extension.
+    path = re.sub(r"(?:[-_.])[A-Za-z0-9_-]{8,64}(?=\.[^.]+$)", "-asset", path)
     return urlunparse((parsed.scheme, parsed.netloc, path, parsed.params, "", ""))
 
 
@@ -65,9 +68,14 @@ class PageParser(HTMLParser):
         self.headings = []
         self.paragraphs = []
         self.links = []
+        self.fragment_ids = set()
 
     def handle_starttag(self, tag, attrs):
         data = dict(attrs)
+        if data.get("id"):
+            self.fragment_ids.add(data["id"])
+        if tag == "a" and data.get("name"):
+            self.fragment_ids.add(data["name"])
         if data.get("data-template"):
             self.templates.add(data["data-template"])
         if tag in {"script", "style", "noscript"}:
@@ -184,6 +192,7 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
             "title": page.title, "meta": page.meta, "canonical": canonical,
             "lang": page.lang, "hreflang": page.hreflang, "robots": robots,
             "jsonld": page.jsonld_values, "images": page.images,
+            "fragmentIds": sorted(page.fragment_ids),
             "structureHash": hashlib.sha256(json.dumps(stable_structure(page.structure), sort_keys=True).encode()).hexdigest(),
             "textHash": hashlib.sha256(" ".join(page.visible_text).encode()).hexdigest(),
         },
@@ -298,6 +307,99 @@ def access_log_sitemap_check(path: Path, sitemap_path: str = "/sitemap.xml") ->
     return {"provided": True, "path": str(path), "requestCount": len(requests), "googlebotRequestCount": len(googlebot), "status": "requested" if requests else "not-requested", "diagnosis": "googlebot-request-observed" if googlebot else ("other-client-request-only" if requests else "no-matching-request")}
 
 
+def internal_link_check(base: str, pages: list[dict], fetcher=fetch) -> dict[str, object]:
+    """Validate same-origin links and fragment targets discovered during a crawl."""
+    origin = urlparse(base)
+    page_by_url = {page.get("url"): page for page in pages if page.get("url")}
+    errors: list[dict[str, str]] = []
+    checked = 0
+    seen: set[tuple[str, str]] = set()
+    for page in pages:
+        page_url = str(page.get("url") or "")
+        for link in (page.get("contentContract") or {}).get("links", []):
+            target = urljoin(page_url, str(link.get("href") or ""))
+            parsed = urlparse(target)
+            if parsed.scheme not in {"http", "https"} or (parsed.scheme, parsed.netloc.lower()) != (origin.scheme, origin.netloc.lower()):
+                continue
+            fragment = parsed.fragment
+            target_url = urlunparse((parsed.scheme, parsed.netloc, parsed.path or "/", parsed.params, parsed.query, ""))
+            key = (target_url, fragment)
+            if key in seen:
+                continue
+            seen.add(key)
+            checked += 1
+            target_page = page_by_url.get(target_url)
+            if target_page and isinstance(target_page.get("contract"), dict):
+                status = target_page.get("status")
+                content_type = target_page.get("content_type")
+                fragment_ids = set(target_page["contract"].get("fragmentIds", []))
+            else:
+                try:
+                    status, content_type, body = fetcher(target_url)
+                    parsed_target = PageParser()
+                    parsed_target.feed(body)
+                    fragment_ids = parsed_target.fragment_ids
+                except Exception as exc:
+                    errors.append({"source": page_url, "url": target_url, "reason": type(exc).__name__})
+                    continue
+            if status != 200 or content_type != "text/html":
+                errors.append({"source": page_url, "url": target_url, "reason": "target did not return HTTP 200 HTML"})
+            elif fragment and fragment not in fragment_ids:
+                errors.append({"source": page_url, "url": target, "reason": "fragment target not found"})
+    return {"ok": not errors, "linksChecked": checked, "errors": errors}
+
+
+def mark_unstable_pages(pages: list[dict]) -> None:
+    """Refetch baseline candidates once and label per-response markup drift."""
+    for page in pages:
+        if not isinstance(page.get("contract"), dict):
+            continue
+        try:
+            status, content_type, body = fetch(page["url"])
+            second = audit_page(page["url"], body, status, content_type)
+            first_contract = page["contract"]
+            second_contract = second["contract"]
+            first_content = page.get("contentContract", {})
+            second_content = second.get("contentContract", {})
+            changed = any(first_contract.get(key) != second_contract.get(key) for key in ("structureHash", "textHash")) or first_content.get("contentHash") != second_content.get("contentHash")
+            page["stability"] = {
+                "status": "unstable" if changed else "stable",
+                "changedBetweenFetches": changed,
+                "secondStructureHash": second_contract.get("structureHash"),
+                "secondTextHash": second_contract.get("textHash"),
+            }
+        except Exception as exc:
+            page["stability"] = {"status": "recapture-failed", "changedBetweenFetches": False, "error": type(exc).__name__}
+
+
+def parse_baseline_reasons(values: list[str], drift_urls: set[str], reason_all: str | None = None) -> dict[str, str]:
+    """Parse per-URL and site-wide reviewer reasons with actionable errors."""
+    reasons: dict[str, str] = {}
+    default = reason_all.strip() if reason_all and reason_all.strip() else ""
+    for value in values:
+        url, separator, reason = value.partition("=")
+        if not separator or not url.strip() or not reason.strip():
+            raise ValueError("each --reason must use URL=REASON")
+        url, reason = url.strip(), reason.strip()
+        if url == "*":
+            if default:
+                raise ValueError("duplicate site-wide baseline change reason")
+            default = reason
+            continue
+        if url in reasons:
+            raise ValueError("duplicate baseline change reason: " + url)
+        if url not in drift_urls:
+            raise ValueError("baseline change reason references a URL without a detected drift: " + url)
+        reasons[url] = reason
+    if default:
+        for url in drift_urls:
+            reasons.setdefault(url, default)
+    missing_reasons = sorted(drift_urls - reasons.keys())
+    if missing_reasons:
+        raise ValueError("every drifting URL requires a reviewer reason: " + ", ".join(missing_reasons))
+    return reasons
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("url")
@@ -309,6 +411,7 @@ def main() -> int:
     parser.add_argument("--languages", help="comma-separated expected languages/locales, e.g. en-GB,es-MX,ja-JP")
     parser.add_argument("--markets", help="comma-separated markets: global,uk,us")
     parser.add_argument("--check-hreflang", action="store_true")
+    parser.add_argument("--check-internal-links", action="store_true", help="validate same-origin links and fragment targets during a crawl")
     parser.add_argument("--check-translation-completeness", action="store_true")
     parser.add_argument("--access-log", type=Path, help="optional local access log for crawler-request diagnosis")
     parser.add_argument("--require-sitemap-request", action="store_true", help="fail unless the supplied access log contains a sitemap request")
@@ -319,12 +422,15 @@ def main() -> int:
     parser.add_argument("--recapture-baseline", type=Path, help="write a reviewed versioned baseline after reviewing every drift")
     parser.add_argument("--baseline-id", help="required stable ID for --recapture-baseline")
     parser.add_argument("--reason", action="append", default=[], metavar="URL=REASON", help="reviewer-approved reason for one drifting URL; repeat for every drift")
+    parser.add_argument("--reason-all", help="reviewer-approved reason applied to every drifting URL during baseline recapture")
     parser.add_argument("--reviewer", help="required for --save-baseline")
     args = parser.parse_args()
     if args.max_pages < 1:
         parser.error("max-pages must be positive")
     if (args.save_baseline or args.baseline) and not args.crawl:
         parser.error("baseline operations require --crawl")
+    if args.check_internal_links and not args.crawl:
+        parser.error("internal link checks require --crawl")
     if args.save_baseline and not (args.reviewer or "").strip():
         parser.error("save-baseline requires --reviewer")
     if args.recapture_baseline:
@@ -422,6 +528,9 @@ def main() -> int:
             crawl["sitemapOriginPolicy"] = "declared-origin" if args.preserve_sitemap_origin else "requested-origin"
             crawl["passed"] = crawl["complete"] and bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
             crawl["url_count"] = len(urls)
+            if args.check_internal_links:
+                crawl["internal_links"] = internal_link_check(base, crawl["pages"])
+                crawl["passed"] = crawl["passed"] and crawl["internal_links"]["ok"]
         except Exception as exc:
             crawl = {"enabled": True, "passed": False, "error": type(exc).__name__, "pages": []}
 
@@ -431,6 +540,8 @@ def main() -> int:
     try:
         current_passed = result["passed"]
         if args.baseline:
+            if args.crawl:
+                mark_unstable_pages(crawl["pages"])
             previous_baseline = json.loads(args.baseline.read_text())
             result["baseline"] = site_baseline.compare(previous_baseline, result)
             result["passed"] = result["passed"] and result["baseline"]["passed"]
@@ -439,20 +550,8 @@ def main() -> int:
                 drift_urls = set(comparison.get("added", [])) | set(comparison.get("removed", []))
                 drift_urls |= {item["url"] for item in comparison.get("changed", []) if isinstance(item, dict) and item.get("url")}
                 drift_urls |= {item["url"] for item in comparison.get("contentChanged", []) if isinstance(item, dict) and item.get("url")}
-                reasons: dict[str, str] = {}
-                for value in args.reason:
-                    url, separator, reason = value.partition("=")
-                    if not separator or not url.strip() or not reason.strip():
-                        raise ValueError("each --reason must use URL=REASON")
-                    url = url.strip()
-                    if url in reasons:
-                        raise ValueError("duplicate baseline change reason")
-                    if url not in drift_urls:
-                        raise ValueError("baseline change reason references a URL without a detected drift")
-                    reasons[url] = reason.strip()
-                missing_reasons = sorted(drift_urls - reasons.keys())
-                if missing_reasons:
-                    raise ValueError("every drifting URL requires a reviewer reason")
+                drift_urls |= set(comparison.get("unstable", []))
+                reasons = parse_baseline_reasons(args.reason, drift_urls, args.reason_all)
                 if not current_passed:
                     raise ValueError("baseline recapture requires a passing current crawl")
                 recapture_report = dict(result)

package/bundled-tools/runtime/site_baseline.py

@@ -36,6 +36,8 @@ def snapshot(
     for page in pages:
         if not page.get("passed") or not isinstance(page.get("contract"), dict):
             raise ValueError("baseline requires successful page contracts")
+        if (page.get("stability") or {}).get("status") == "unstable":
+            raise ValueError("baseline requires stable page contracts")
         if page["url"] in contracts:
             raise ValueError("duplicate page URL")
         if urlparse(page["url"]).query:
@@ -75,11 +77,16 @@ def compare(baseline: dict, report: dict) -> dict:
     expected = baseline["pages"]
     added, removed = sorted(current.keys() - expected.keys()), sorted(expected.keys() - current.keys())
     changes = []
+    unstable = []
     for url in sorted(expected.keys() & current.keys()):
         actual = current[url]
         if not isinstance(actual, dict):
             errors.append("missing page contract: " + url)
             continue
+        page = next((item for item in crawl_pages if item.get("url") == url), {})
+        if (page.get("stability") or {}).get("status") == "unstable":
+            unstable.append(url)
+            continue
         fields = sorted(key for key in expected[url].keys() | actual.keys() if expected[url].get(key) != actual.get(key))
         if fields:
             changes.append({"url": url, "fields": fields})
@@ -88,6 +95,8 @@ def compare(baseline: dict, report: dict) -> dict:
     content_not_compared = []
     if expected_content:
         for url in sorted(expected_content.keys() & current_content.keys()):
+            if url in unstable:
+                continue
             expected_contract = expected_content[url]
             current_contract = current_content[url]
             ignored_legacy_fields = {"images", "imageAlts"} if "images" not in expected_contract else set()
@@ -99,9 +108,10 @@ def compare(baseline: dict, report: dict) -> dict:
         missing_content = sorted(expected_content.keys() - current_content.keys())
         if missing_content:
             errors.append("missing content contract: " + ", ".join(missing_content))
-    return {"passed": not errors and not added and not removed and not changes and not content_changes,
+    return {"passed": not errors and not added and not removed and not changes and not content_changes and not unstable,
             "errors": errors, "added": added, "removed": removed, "changed": changes,
             "contentChanged": content_changes,
+            "unstable": unstable,
             "contentNotCompared": content_not_compared,
             "excludedQueryUrls": query_urls}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.35",
+  "version": "0.7.37",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",