@topy-ai/maggie 0.7.38 → 0.7.41

package/bundled-tools/clis/site_audit.py

@@ -8,6 +8,7 @@ import hashlib
 import json
 import re
 import sys
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from urllib.parse import urljoin, urlparse, urlunparse
 from html.parser import HTMLParser
@@ -69,9 +70,20 @@ class PageParser(HTMLParser):
         self.paragraphs = []
         self.links = []
         self.fragment_ids = set()
+        self.primary_navigation_links = []
+        self._header_depth = 0
+        self._nav_depth = 0
+        self._primary_nav_depth = 0
 
     def handle_starttag(self, tag, attrs):
         data = dict(attrs)
+        if tag == "header":
+            self._header_depth += 1
+        if tag == "nav":
+            self._nav_depth += 1
+            label = f"{data.get('aria-label', '')} {data.get('id', '')} {data.get('class', '')}".lower()
+            if self._header_depth or any(token in label for token in ("primary", "main", "navigation")):
+                self._primary_nav_depth += 1
         if data.get("id"):
             self.fragment_ids.add(data["id"])
         if tag == "a" and data.get("name"):
@@ -106,6 +118,8 @@ class PageParser(HTMLParser):
             self._jsonld = []
         elif tag == "a" and data.get("href"):
             self.anchors += 1
+            if self._primary_nav_depth:
+                self.primary_navigation_links.append(data.get("href", ""))
         elif tag == "img":
             self.images.append({"src": data.get("src", ""), "alt": data.get("alt")})
 
@@ -132,6 +146,12 @@ class PageParser(HTMLParser):
             except json.JSONDecodeError:
                 self.jsonld_values.append(None)
             self._jsonld = None
+        if tag == "nav":
+            self._nav_depth = max(0, self._nav_depth - 1)
+            if self._primary_nav_depth:
+                self._primary_nav_depth -= 1
+        elif tag == "header":
+            self._header_depth = max(0, self._header_depth - 1)
 
     def handle_data(self, data):
         if not self.hidden_depth and data.strip():
@@ -157,6 +177,20 @@ def fetch(url: str, evidence: dict | None = None) -> tuple[int, str, str]:
         return response.status, response.headers.get_content_type(), body
 
 
+def indexability_if_indexed(page: PageParser, robots: list[str]) -> dict:
+    """Explain what a noindex page would fail if it became indexable."""
+    tokens = [token.strip().rsplit(":", 1)[-1] for directive in robots for token in directive.split(",")]
+    blocked = sorted(set(tokens) & {"noindex", "none"})
+    checks = {
+        "title": bool(page.title),
+        "description": bool(page.meta.get("description")),
+        "canonical": bool(page.canonical) and urlparse(page.canonical).fragment == "",
+        "headings": bool(page.headings) and page.h1 == 1,
+        "jsonld": page.jsonld > 0 and all(item is not None for item in page.jsonld_values),
+    }
+    return {"applicable": bool(blocked), "blockedBy": blocked, "wouldPass": all(checks.values()) if blocked else None, "checks": checks if blocked else {}}
+
+
 def audit_page(url: str, html: str, status: int, content_type: str, expected_languages: set[str] | None = None, response_evidence: dict | None = None) -> dict:
     page = PageParser()
     page.feed(html)
@@ -165,6 +199,7 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
     robots = page.robots_directives + [value.lower() for value in response_evidence["xRobotsTag"]]
     robots_tokens = [token.strip() for directive in robots for token in directive.split(",")]
     robots_tokens = [token.rsplit(":", 1)[-1].strip() for token in robots_tokens]
+    hypothetical = indexability_if_indexed(page, robots)
     return {
         "url": url,
         "status": status,
@@ -193,6 +228,7 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
             "lang": page.lang, "hreflang": page.hreflang, "robots": robots,
             "jsonld": page.jsonld_values, "images": page.images,
             "fragmentIds": sorted(page.fragment_ids),
+            "primaryNavigationLinks": page.primary_navigation_links,
             "structureHash": hashlib.sha256(json.dumps(stable_structure(page.structure), sort_keys=True).encode()).hexdigest(),
             "textHash": hashlib.sha256(" ".join(page.visible_text).encode()).hexdigest(),
         },
@@ -215,9 +251,38 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
         "robots": not robots or not any(token in {"noindex", "none", "nofollow"} for token in robots_tokens),
         "robots_directives": robots,
         "robots_conflict": len({token for token in robots_tokens if token in {"index", "noindex", "follow", "nofollow", "none"}} & {"index", "noindex"}) > 1 or len({token for token in robots_tokens if token in {"follow", "nofollow", "none"}} & {"follow", "nofollow"}) > 1,
+        "primary_navigation_links": page.primary_navigation_links,
+        "indexabilityIfIndexed": hypothetical,
     }
 
 
+def primary_navigation_check(base: str, page: PageParser, fetcher=fetch) -> dict:
+    """Ensure links presented as primary navigation are indexable destinations."""
+    origin = urlparse(base).netloc
+    routes = []
+    for href in page.primary_navigation_links:
+        target = urljoin(base + "/", href)
+        parsed = urlparse(target)
+        if parsed.scheme not in {"http", "https"} or parsed.netloc != origin:
+            continue
+        target = urlunparse((parsed.scheme, parsed.netloc, parsed.path or "/", "", "", ""))
+        if target not in routes:
+            routes.append(target)
+    violations = []
+    for target in routes:
+        try:
+            status, content_type, body = fetcher(target)
+            destination = PageParser(); destination.feed(body)
+            directives = [item.lower() for item in destination.robots_directives]
+            tokens = [token.strip().rsplit(":", 1)[-1] for directive in directives for token in directive.split(",")]
+            blocked = sorted(set(tokens) & {"noindex", "nofollow", "none"})
+            if blocked:
+                violations.append({"url": target, "status": status, "directives": directives, "blocked": blocked})
+        except Exception as exc:
+            violations.append({"url": target, "error": type(exc).__name__})
+    return {"ok": not violations, "links": routes, "violations": violations}
+
+
 def summarize_crawl(pages: list[dict]) -> dict:
     """Count captured evidence, preserving regional/script locale distinctions."""
     groups = {}
@@ -400,6 +465,12 @@ def parse_baseline_reasons(values: list[str], drift_urls: set[str], reason_all:
     return reasons
 
 
+def baseline_ack_expiry(days: int) -> str:
+    if not 1 <= days <= 3650:
+        raise ValueError("baseline acknowledgement TTL must be between 1 and 3650 days")
+    return (datetime.now(timezone.utc) + timedelta(days=days)).isoformat().replace("+00:00", "Z")
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("url")
@@ -423,6 +494,7 @@ def main() -> int:
     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("--reason-ttl-days", type=int, default=30, help="expiry for a reviewed baseline drift acknowledgement (default: 30)")
     parser.add_argument("--reviewer", help="required for --save-baseline")
     args = parser.parse_args()
     if args.max_pages < 1:
@@ -455,7 +527,8 @@ def main() -> int:
     base = args.url.rstrip("/")
     checks = {}
     try:
-        status, content_type, html = fetch(base)
+        homepage_response = {}
+        status, content_type, html = fetch(base, homepage_response)
         page = PageParser()
         page.feed(html)
         checks["homepage"] = {"ok": status == 200 and content_type == "text/html", "status": status, "content_type": content_type}
@@ -470,9 +543,11 @@ def main() -> int:
         checks["jsonld"] = {"ok": page.jsonld > 0 and all(item is not None for item in page.jsonld_values), "count": page.jsonld}
         checks["entity_jsonld"] = {"ok": any(isinstance(item, dict) and item.get("@type") and (item.get("url") or item.get("@id")) for item in page.jsonld_values), "count": page.jsonld}
         checks["crawlable_links"] = {"ok": page.anchors > 0, "count": page.anchors}
+        checks["primary_navigation_indexability"] = primary_navigation_check(base, page)
         robots_tokens = [token.strip() for directive in page.robots_directives for token in directive.split(",")]
         checks["robots_directive"] = {"ok": not page.robots_directives or not any(token in {"noindex", "none", "nofollow"} for token in robots_tokens), "directives": page.robots_directives}
         checks["robots_conflict"] = {"ok": not (len({token for token in robots_tokens if token in {"index", "noindex"}}) > 1 or len({token for token in robots_tokens if token in {"follow", "nofollow"}}) > 1), "directives": page.robots_directives}
+        checks["indexability_if_indexed"] = {"ok": True, **indexability_if_indexed(page, page.robots_directives + [value.lower() for value in homepage_response.get("xRobotsTag", [])])}
         if args.check_hreflang or args.check_translation_completeness:
             checks["hreflang"] = hreflang_check(base, page, expected_languages) if args.check_hreflang else {"ok": True, "links": page.hreflang}
             if args.check_translation_completeness and expected_languages:
@@ -565,6 +640,7 @@ def main() -> int:
                     baseline_id=args.baseline_id,
                     supersedes=previous_baseline.get("baselineId") or site_baseline.baseline_fingerprint(previous_baseline),
                     change_reasons=reasons,
+                    approval_expires_at=baseline_ack_expiry(args.reason_ttl_days),
                 )
                 site_baseline.save(args.recapture_baseline, recaptured)
                 result["baselineRecapture"] = {

package/bundled-tools/integrations/analytics.md

@@ -60,6 +60,20 @@ GSC data is read-only in this starter. Any query, page, or indexing report must
 show its date window and property so an agent does not confuse an empty result
 with a failed connection.
 
+The GSC readiness evidence contract is explicit and can be checked before the
+combined release gate:
+
+```bash
+maggie analytics gsc-readiness \
+  --gsc-evidence .maggie/gsc-readiness.json
+```
+
+The evidence must cover property/verification, canonical origin, robots,
+sitemap, read-only authorization, query/readback, and production smoke. Use
+`--gsc-evidence ... --require-gsc` with `maggie analytics release-gate` to make
+those checks blocking. The command does not authorize a property or mutate
+Search Console.
+
 Run the deterministic configuration gate before enabling production tracking:
 
 ```bash

package/bundled-tools/runtime/site_baseline.py

@@ -21,6 +21,7 @@ def snapshot(
     baseline_id: str | None = None,
     supersedes: str | None = None,
     change_reasons: dict[str, str] | None = None,
+    approval_expires_at: str | None = None,
 ) -> dict:
     if not reviewer.strip():
         raise ValueError("baseline requires a reviewer")
@@ -58,6 +59,8 @@ def snapshot(
         result["supersedes"] = supersedes
     if change_reasons:
         result["approvedChangeReasons"] = {key: change_reasons[key] for key in sorted(change_reasons)}
+    if approval_expires_at:
+        result["approval"] = {"type": "reviewed-drift-acknowledgement", "expiresAt": approval_expires_at}
     return result
 
 

package/package.json

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

package/references/browser-inspection.md

@@ -27,6 +27,27 @@ interaction states and triggers
 responsive differences
 ```
 
+Behavioral checks may be declared instead of hidden in a bespoke script. The
+manifest is safe to commit because input values are not copied into evidence:
+
+```json
+{
+  "schemaVersion": "maggie-browser-interactions.v1",
+  "steps": [
+    {"id": "open", "action": "click", "selector": "[data-menu]"},
+    {"id": "visible", "action": "assert-visible", "selector": "[data-drawer]"},
+    {"id": "styles", "action": "assert-style", "selector": "[data-drawer]", "property": "display", "value": "block"},
+    {"id": "privacy", "action": "assert-no-request", "origin": "third-party.example"}
+  ]
+}
+```
+
+Run it with `maggie browser-audit ... --interactions .maggie/interactions.json`.
+Supported actions cover click, fill, type, select, press, wait, visibility and
+state assertions, computed-style assertions, and new-request assertions. The
+browser adapter owns the session and the audit records only step IDs and
+redacted outcomes.
+
 If a target requires login, a bot challenge, a consent interaction, or a
 private browser profile, stop at that boundary and ask the user to provide
 authorized access. Do not bypass access controls or record cookies in project