@topy-ai/maggie 0.5.0 → 0.6.0

package/README.md

@@ -46,7 +46,7 @@ Then invoke the installed skills from your coding agent, for example:
 
 Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
-package ships 16 installable skills and a local-first MaggieDash foundation.
+package ships 18 installable skills and a local-first MaggieDash foundation.
 
 ## Command surface
 
@@ -66,6 +66,9 @@ maggie memory ...                # confirmed preferences and lessons
 maggie feedback ...              # redact, preview, submit, list
 maggie localization ...          # plan, validate, review, publish, stale
 maggie service ...               # import, sync, generate, validate
+maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
+maggie seo images ...             # inventory, variants, confirmation, validate
+maggie seo sitemap ...            # typed plan, validate, apply, rollback
 maggie deployment | migration | release | analytics | schedule
 maggie api lifecycle | site-audit | ops audit
 ```
@@ -77,11 +80,38 @@ history only and is not an installable package skill.
 with `--confirm`, removes only known retired EmDash artifacts. It preserves
 `docs/de-emdash-*` migration history and `.maggie` marketplace state.
 
+### SEO performance, images, and sitemaps
+
+The SEO workflow keeps performance evidence separate from deterministic HTML
+correctness checks. Performance reports use multiple samples, exclude duplicate
+PageSpeed `fetchTime` observations, and report median/range before comparing a
+baseline:
+
+```bash
+maggie seo performance --url https://example.com --strategy mobile,desktop \
+  --samples 3 --spacing-seconds 30 --output docs/performance-report.json
+```
+
+Responsive image planning emits only confirmed candidates in `srcset`, while
+sitemap planning groups content types, emits valid empty chunk 1 files, and
+rejects relative or off-origin `<loc>` values:
+
+```bash
+maggie seo images inventory --project . --output docs/image-inventory.json
+maggie seo images plan --inventory docs/image-inventory.json --output docs/image-variants.json
+maggie seo sitemap plan --origin https://example.com --routes-file docs/routes.tsv \
+  --output docs/sitemap-plan.json
+```
+
+Read the [performance PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/seo-performance-cwv-prd.md)
+and [image/sitemap PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/image-sitemap-structure-prd.md)
+for adapter, privacy, apply, rollback, and release gates.
+
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.2.9 update --project . --force
-npx @topy-ai/maggie@0.2.9 cleanup --project .
+npx @topy-ai/maggie@0.6.0 update --project . --force
+npx @topy-ai/maggie@0.6.0 cleanup --project .
 ```
 
 ## MaggieDash lifecycle

package/bin/maggie.js

@@ -109,6 +109,7 @@ Usage:
   maggie api lifecycle --project PATH [--execute --allow-quota]
   maggie memory <init|list|search|context|add|record-error|transition|export> --project PATH
   maggie localization <plan|preview|validate|review|publish|stale|glossary> [options]
+  maggie seo performance|images|sitemap [options]
   maggie feedback <collect|preview|submit|list> [options]
   maggie site-audit URL [--crawl] [--languages en-GB,es-MX,ja-JP] [--check-hreflang]
   maggie ops audit --project PATH
@@ -208,7 +209,11 @@ function install(args) {
   const tools = join(root, "tools");
   if (existsSync(TOOLS_ROOT)) {
     for (const group of ["clis", "runtime", "integrations"]) {
-      if (existsSync(join(TOOLS_ROOT, group))) copyIfMissing(join(TOOLS_ROOT, group), join(tools, group), force);
+      if (existsSync(join(TOOLS_ROOT, group))) {
+        const target = join(tools, group);
+        if (existsSync(target)) syncTree(join(TOOLS_ROOT, group), target, force);
+        else copyIfMissing(join(TOOLS_ROOT, group), target, force);
+      }
     }
   }
   if (existsSync(join(DESIGN_ROOT, "SPA-DESIGN.md"))) {
@@ -244,7 +249,10 @@ function update(args) {
     if (existsSync(REFERENCES_ROOT) && existsSync(join(agentRoot, "references"))) updated += syncTree(REFERENCES_ROOT, join(agentRoot, "references"), force);
   }
   const tools = join(root, "tools");
-  if (existsSync(TOOLS_ROOT)) for (const group of ["clis", "integrations"]) if (existsSync(join(tools, group))) updated += syncTree(join(TOOLS_ROOT, group), join(tools, group), force);
+  if (existsSync(TOOLS_ROOT)) for (const group of ["clis", "runtime", "integrations"]) if (existsSync(join(TOOLS_ROOT, group))) {
+    const target = join(tools, group);
+    if (existsSync(target)) updated += syncTree(join(TOOLS_ROOT, group), target, force);
+  }
   if (existsSync(join(DESIGN_ROOT, "SPA-DESIGN.md")) && existsSync(join(root, ".maggie", "design-reference"))) {
     updated += syncTree(DESIGN_ROOT, join(root, ".maggie", "design-reference"), force);
   }
@@ -282,6 +290,13 @@ function service(args) {
   process.exitCode = result.status ?? 1;
 }
 
+function seo(args) {
+  const command = args[0];
+  const scripts = { performance: "maggie_performance.py", images: "maggie_images.py", sitemap: "maggie_sitemap.py" };
+  if (!scripts[command]) throw new Error("seo command must be performance, images, or sitemap");
+  workflowCli(scripts[command], args.slice(1));
+}
+
 function workflowCli(name, args) {
   const root = projectRoot(args);
   const script = join(root, "tools", "clis", name);
@@ -358,6 +373,7 @@ try {
   else if (command === "auth") workflowCli("maggie_auth.py", args);
   else if (command === "blog") workflowCli("maggie_blog.py", args);
   else if (command === "service") service(args);
+  else if (command === "seo") seo(args);
   else if (command === "ops") workflowCli("maggie_ops.py", args);
   else if (command === "deployment") workflowCli("maggie_deployment.py", args);
   else if (command === "migration") workflowCli("maggie_migration.py", args);

package/bundled-contracts/maggie-seo/image-variants-v1.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.noblox.app/maggie-seo/image-variants-v1.schema.json",
+  "title": "Maggie image variants manifest",
+  "type": "object",
+  "required": ["schemaVersion", "manifestId", "createdAt", "assets", "provenance"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-seo-image-variants.v1"},
+    "manifestId": {"type": "string", "pattern": "^images-[A-Za-z0-9_-]+$"},
+    "createdAt": {"type": "string", "format": "date-time"},
+    "assets": {"type": "array", "items": {"type": "object", "required": ["assetId", "source", "variants", "markupPolicy"]}},
+    "provenance": {"type": "object", "required": ["redactions"]}
+  }
+}

package/bundled-contracts/maggie-seo/performance-report-v1.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.noblox.app/maggie-seo/performance-report-v1.schema.json",
+  "title": "Maggie SEO performance report",
+  "type": "object",
+  "required": ["schemaVersion", "reportId", "createdAt", "provider", "policy", "pages", "summary", "provenance"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-seo-performance.v1"},
+    "reportId": {"type": "string", "pattern": "^perf-[A-Za-z0-9_-]+$"},
+    "createdAt": {"type": "string", "format": "date-time"},
+    "provider": {"const": "pagespeed-insights"},
+    "providerApiVersion": {"type": "string"},
+    "project": {"type": "object", "additionalProperties": true},
+    "policy": {"$ref": "#/$defs/policy"},
+    "pages": {"type": "array", "items": {"$ref": "#/$defs/page"}},
+    "summary": {"type": "object", "required": ["status"], "properties": {"status": {"enum": ["pass", "fail", "inconclusive"]}}, "additionalProperties": true},
+    "provenance": {"type": "object", "required": ["commands", "redactions"], "additionalProperties": true}
+  },
+  "$defs": {
+    "policy": {
+      "type": "object",
+      "required": ["strategies", "requestedSamples", "minimumIndependentSamples", "spacingSeconds", "duplicateFetchTimePolicy"],
+      "properties": {
+        "strategies": {"type": "array", "items": {"enum": ["desktop", "mobile"]}},
+        "requestedSamples": {"type": "integer", "minimum": 1},
+        "minimumIndependentSamples": {"type": "integer", "minimum": 1},
+        "spacingSeconds": {"type": "number", "minimum": 0},
+        "duplicateFetchTimePolicy": {"const": "exclude"}
+      },
+      "additionalProperties": true
+    },
+    "page": {
+      "type": "object",
+      "required": ["requestedUrl", "strategy", "samples", "aggregate", "fieldData", "comparison"],
+      "properties": {
+        "requestedUrl": {"type": "string", "format": "uri"},
+        "strategy": {"enum": ["desktop", "mobile"]},
+        "samples": {"type": "array"},
+        "aggregate": {"type": "object"},
+        "fieldData": {"type": "object"},
+        "comparison": {"type": "object"}
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/bundled-contracts/maggie-seo/sitemap-plan-v1.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.noblox.app/maggie-seo/sitemap-plan-v1.schema.json",
+  "title": "Maggie structured sitemap plan",
+  "type": "object",
+  "required": ["schemaVersion", "planId", "origin", "groups", "index", "redirects", "validation"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-seo-sitemap-plan.v1"},
+    "planId": {"type": "string", "pattern": "^sitemap-[A-Za-z0-9_-]+$"},
+    "origin": {"type": "string", "format": "uri"},
+    "groups": {"type": "array"},
+    "index": {"type": "object"},
+    "redirects": {"type": "array"},
+    "validation": {"type": "object", "required": ["status", "errors", "warnings"]}
+  }
+}

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -19,6 +19,39 @@ voice, CTA alignment, and observed search/AI outcomes.
 
 ## Choose the mode
 
+For sampled PageSpeed performance and Core Web Vitals evidence, run:
+
+```bash
+maggie seo performance --url https://example.com --strategy mobile,desktop \
+  --samples 3 --spacing-seconds 30 --output docs/performance-report.json
+```
+
+The performance workflow excludes duplicate provider `fetchTime` observations,
+reports median/range, and marks a baseline comparison `inconclusive` when it
+does not have enough independent samples. `PAGESPEED_API_KEY` is optional for
+the provider but is never written to reports. Read the [performance PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/seo-performance-cwv-prd.md)
+when selecting thresholds or adding a provider.
+
+For responsive image planning and typed sitemap planning, run:
+
+```bash
+maggie seo images inventory --project . --output docs/image-inventory.json
+maggie seo images plan --inventory docs/image-inventory.json --output docs/image-variants.json
+maggie seo images validate --manifest docs/image-variants.json
+maggie seo sitemap plan --origin https://example.com --routes-file docs/routes.tsv \
+  --output docs/sitemap-plan.json
+maggie seo sitemap validate --plan docs/sitemap-plan.json
+# After an approved host adapter apply, rollback uses its exact backup manifest.
+maggie seo sitemap rollback --backup-manifest .maggie-sitemap-backups/<plan>/backup-manifest.json \
+  --public-dir public --confirm
+```
+
+Only confirmed image variants may enter `srcset`; `apply` requires an explicit
+confirmation and host adapter. Sitemap plans keep content types separate,
+emit chunk 1 for empty enabled types, enforce absolute same-origin URLs, and
+record redirects for removed sitemap files. Read the [image and sitemap PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/image-sitemap-structure-prd.md)
+for adapter and rollback rules.
+
 For a deterministic technical smoke check, run:
 
 ```bash
@@ -30,7 +63,10 @@ interpretation, and content creation remain agent-reviewed decisions.
 With `--crawl`, it resolves sitemap indexes and audits every listed HTML route
 for HTTP 200, one H1, title/description, locale, canonical, Open Graph/Twitter
 metadata, valid entity JSON-LD, and image alt text. Non-HTML endpoints such as
-RSS must not be included in the HTML page sitemap.
+RSS must not be included in the HTML page sitemap. Sitemap `<loc>` values must
+be absolute HTTP(S) URLs; the audit reports relative values as a failure even
+when it can resolve them for continued crawling, so one malformed entry cannot
+hide a protocol violation.
 Use `--output <project>/docs/site-audit.json` to persist the evidence used by
 the release review.
 

package/bundled-tools/clis/maggie_images.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Inventory and validate safe responsive image variant manifests."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_media import confirm_variants, inventory_project, plan_variants, validate_manifest  # noqa: E402
+
+
+def write_json(path: str, value: dict) -> None:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(value, indent=2) + "\n", encoding="utf-8")
+
+
+def check_url(url: str) -> int:
+    request = Request(url, method="HEAD", headers={"User-Agent": "Maggie-SEO-Images/1.0"})
+    with urlopen(request, timeout=20) as response:
+        return response.status
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="command", required=True)
+    inventory = sub.add_parser("inventory")
+    inventory.add_argument("--project", default=".")
+    inventory.add_argument("--output", required=True)
+    plan = sub.add_parser("plan")
+    plan.add_argument("--inventory", required=True)
+    plan.add_argument("--widths", default="320,480,768,1080,1440,1920")
+    plan.add_argument("--provider", choices=("unsplash", "cloudinary"))
+    plan.add_argument("--confirm-external", action="store_true")
+    plan.add_argument("--output", required=True)
+    confirm = sub.add_parser("confirm")
+    confirm.add_argument("--manifest", required=True)
+    confirm.add_argument("--output", required=True)
+    validate = sub.add_parser("validate")
+    validate.add_argument("--manifest", required=True)
+    apply = sub.add_parser("apply")
+    apply.add_argument("--manifest", required=True)
+    apply.add_argument("--adapter", choices=("manifest",), required=True)
+    apply.add_argument("--output", required=True)
+    apply.add_argument("--confirm", action="store_true")
+    args = parser.parse_args()
+    try:
+        if args.command == "inventory":
+            result = inventory_project(args.project)
+            write_json(args.output, result)
+            print(json.dumps({"assets": len(result["assets"]), "output": str(Path(args.output).resolve())}, indent=2))
+            return 0
+        if args.command == "plan":
+            result = plan_variants(json.loads(Path(args.inventory).read_text(encoding="utf-8")), [int(item) for item in args.widths.split(",")], args.provider)
+            write_json(args.output, result)
+            print(json.dumps({"assets": len(result["assets"]), "output": str(Path(args.output).resolve())}, indent=2))
+            return 0
+        manifest = json.loads(Path(args.manifest).read_text(encoding="utf-8"))
+        if args.command == "confirm":
+            result = confirm_variants(manifest, check_url)
+            write_json(args.output, result)
+            print(json.dumps({"errors": validate_manifest(result), "output": str(Path(args.output).resolve())}, indent=2))
+            return 0 if not validate_manifest(result) else 1
+        if args.command == "validate":
+            errors = validate_manifest(manifest)
+            print(json.dumps({"status": "pass" if not errors else "fail", "errors": errors}, indent=2))
+            return 0 if not errors else 1
+        if not args.confirm:
+            raise ValueError("apply requires --confirm")
+        errors = validate_manifest(manifest)
+        if errors:
+            raise ValueError("manifest is invalid: " + "; ".join(errors))
+        applied = {**manifest, "apply": {"adapter": args.adapter, "status": "validated-local-manifest", "publicWrite": False}}
+        write_json(args.output, applied)
+        print(json.dumps({"status": applied["apply"]["status"], "publicWrite": False, "output": str(Path(args.output).resolve())}, indent=2))
+        return 0
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as exc:
+        parser.error(str(exc))
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_performance.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Measure public pages with sampled PageSpeed evidence."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_pagespeed import STRATEGIES, fetch_pagespeed, load_json, make_report, validate_public_url  # noqa: E402
+
+
+def urls_from_args(args: argparse.Namespace) -> list[str]:
+    urls = list(args.url or [])
+    if args.url_file:
+        urls.extend(line.strip() for line in Path(args.url_file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.lstrip().startswith("#"))
+    unique = list(dict.fromkeys(urls))
+    if not unique:
+        raise ValueError("at least one --url or --url-file is required")
+    for url in unique:
+        validate_public_url(url)
+    return unique
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--url", action="append")
+    parser.add_argument("--url-file")
+    parser.add_argument("--strategy", default="mobile")
+    parser.add_argument("--samples", type=int, default=3)
+    parser.add_argument("--spacing-seconds", type=float, default=30)
+    parser.add_argument("--categories", default="performance")
+    parser.add_argument("--locale")
+    parser.add_argument("--fixture", help="JSON fixture containing an array of provider responses")
+    parser.add_argument("--baseline")
+    parser.add_argument("--output")
+    parser.add_argument("--fail-on", choices=("regression", "complete"), default=None)
+    parser.add_argument("--allow-low-sample", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+    try:
+        urls = urls_from_args(args)
+        strategies = [item.strip() for item in args.strategy.split(",") if item.strip()]
+        if not strategies or any(item not in STRATEGIES for item in strategies):
+            raise ValueError("strategy must contain only desktop and mobile")
+        if args.samples < 1 or (args.samples < 3 and not args.allow_low_sample):
+            raise ValueError("samples must be at least 3 unless --allow-low-sample is supplied")
+        if args.spacing_seconds < 0:
+            raise ValueError("spacing-seconds must not be negative")
+        planned_calls = len(urls) * len(strategies) * args.samples
+        if args.dry_run:
+            print(json.dumps({"urls": len(urls), "strategies": strategies, "samples": args.samples, "plannedProviderCalls": planned_calls, "spacingSeconds": args.spacing_seconds}, indent=2))
+            return 0
+        fixture_values = load_json(args.fixture) if args.fixture else None
+        fixture_values = fixture_values.get("responses", fixture_values) if fixture_values is not None else None
+        fixture_index = 0
+
+        def fetcher(url: str, strategy: str) -> dict:
+            nonlocal fixture_index
+            if fixture_values is not None:
+                if not isinstance(fixture_values, list) or not fixture_values:
+                    raise ValueError("fixture must contain a non-empty response array")
+                response = fixture_values[min(fixture_index, len(fixture_values) - 1)]
+                fixture_index += 1
+                return response
+            return fetch_pagespeed(url, strategy, [item.strip() for item in args.categories.split(",") if item.strip()], args.locale, os.environ.get("PAGESPEED_API_KEY"))
+
+        baseline = load_json(args.baseline) if args.baseline else None
+        report = make_report(urls, strategies, args.samples, args.spacing_seconds, fetcher, baseline)
+        if args.output:
+            output = Path(args.output)
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+        print(json.dumps(report, indent=2))
+        if args.fail_on == "regression" and report["summary"]["status"] == "fail":
+            return 2
+        if args.fail_on == "complete" and report["summary"]["status"] != "pass":
+            return 2
+        return 0
+    except (OSError, ValueError) as exc:
+        parser.error(str(exc))
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_sitemap.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Plan and validate typed, conservative XML sitemaps."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_sitemap import build_plan, parse_routes, validate_plan_data  # noqa: E402
+
+
+def write_json(path: str, value: dict) -> None:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(value, indent=2) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="command", required=True)
+    plan = sub.add_parser("plan")
+    plan.add_argument("--origin", required=True)
+    plan.add_argument("--routes-file", required=True)
+    plan.add_argument("--content-types", default="pages,posts,topics")
+    plan.add_argument("--chunk-target", type=int, default=500)
+    plan.add_argument("--previous-manifest")
+    plan.add_argument("--output", required=True)
+    validate = sub.add_parser("validate")
+    validate.add_argument("--plan", required=True)
+    apply = sub.add_parser("apply")
+    apply.add_argument("--plan", required=True)
+    apply.add_argument("--public-dir", required=True)
+    apply.add_argument("--backup-dir")
+    apply.add_argument("--confirm", action="store_true")
+    rollback = sub.add_parser("rollback")
+    rollback.add_argument("--backup-manifest", required=True)
+    rollback.add_argument("--public-dir", required=True)
+    rollback.add_argument("--confirm", action="store_true")
+    args = parser.parse_args()
+    try:
+        if args.command == "plan":
+            previous = json.loads(Path(args.previous_manifest).read_text(encoding="utf-8")) if args.previous_manifest else None
+            result = build_plan(parse_routes(Path(args.routes_file).read_text(encoding="utf-8")), args.origin, {item.strip() for item in args.content_types.split(",") if item.strip()}, args.chunk_target, previous)
+            write_json(args.output, result)
+            print(json.dumps({"status": result["validation"]["status"], "groups": len(result["groups"]), "redirects": len(result["redirects"]), "output": str(Path(args.output).resolve())}, indent=2))
+            return 0 if result["validation"]["status"] == "pass" else 1
+        if args.command == "rollback":
+            if not args.confirm:
+                raise ValueError("rollback requires --confirm")
+            backup = json.loads(Path(args.backup_manifest).read_text(encoding="utf-8"))
+            public = Path(args.public_dir)
+            restored = 0
+            for item in backup.get("files", []):
+                destination = public / item["filename"]
+                source = Path(args.backup_manifest).parent / item["filename"]
+                if item["existed"]:
+                    destination.write_bytes(source.read_bytes())
+                    restored += 1
+                elif destination.exists() and hashlib.sha256(destination.read_bytes()).hexdigest() == item["appliedSha256"]:
+                    destination.unlink()
+                    restored += 1
+            print(json.dumps({"status": "rolled-back", "restored": restored}, indent=2))
+            return 0
+        plan_value = json.loads(Path(args.plan).read_text(encoding="utf-8"))
+        if args.command == "validate":
+            result = validate_plan_data(plan_value)
+            print(json.dumps(result, indent=2))
+            return 0 if result["status"] == "pass" else 1
+        if not args.confirm:
+            raise ValueError("apply requires --confirm")
+        validation = validate_plan_data(plan_value)
+        if validation["status"] != "pass":
+            raise ValueError("plan is invalid: " + "; ".join(validation["errors"]))
+        target = Path(args.public_dir)
+        target.mkdir(parents=True, exist_ok=True)
+        backup_root = Path(args.backup_dir) if args.backup_dir else target / ".maggie-sitemap-backups" / plan_value["planId"]
+        backup_root.mkdir(parents=True, exist_ok=True)
+        backup_files = []
+        output_files = [*(chunk for group in plan_value.get("groups", []) for chunk in group.get("chunks", [])), {"filename": "sitemap.xml", "xml": plan_value["index"]["xml"]}]
+        for item in output_files:
+            destination = target / item["filename"]
+            existed = destination.exists()
+            if existed:
+                (backup_root / item["filename"]).parent.mkdir(parents=True, exist_ok=True)
+                (backup_root / item["filename"]).write_bytes(destination.read_bytes())
+            content = item["xml"].encode("utf-8")
+            backup_files.append({"filename": item["filename"], "existed": existed, "appliedSha256": hashlib.sha256(content).hexdigest()})
+        for group in plan_value.get("groups", []):
+            for chunk in group.get("chunks", []):
+                (target / chunk["filename"]).write_text(chunk["xml"], encoding="utf-8")
+        (target / "sitemap.xml").write_text(plan_value["index"]["xml"], encoding="utf-8")
+        if plan_value.get("redirects"):
+            write_json(str(target / "sitemap-redirect-plan.json"), {"redirects": plan_value["redirects"]})
+        backup_manifest = {"schemaVersion": "maggie-seo-sitemap-rollback.v1", "planId": plan_value["planId"], "publicDir": str(target.resolve()), "files": backup_files}
+        write_json(str(backup_root / "backup-manifest.json"), backup_manifest)
+        print(json.dumps({"status": "applied-local-public-dir", "publicWrite": True, "files": len(output_files), "backupManifest": str((backup_root / "backup-manifest.json").resolve())}, indent=2))
+        return 0
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as exc:
+        parser.error(str(exc))
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/site_audit.py

@@ -134,10 +134,11 @@ def hreflang_check(url: str, page: PageParser, expected: set[str]) -> dict:
     return {"ok": not missing and not reciprocal_errors, "missing": missing, "reciprocal_errors": reciprocal_errors, "links": links}
 
 
-def sitemap_urls(base: str) -> list[str]:
-    """Resolve a sitemap index and return its public page URLs."""
+def sitemap_urls(base: str) -> tuple[list[str], list[dict[str, str]]]:
+    """Resolve a sitemap index and return page URLs plus raw loc violations."""
     pending = [urljoin(base + "/", "sitemap.xml")]
     pages = []
+    violations = []
     seen = set()
     while pending:
         sitemap_url = pending.pop(0)
@@ -145,12 +146,16 @@ def sitemap_urls(base: str) -> list[str]:
             continue
         seen.add(sitemap_url)
         _, _, body = fetch(sitemap_url)
-        locs = [urljoin(base + "/", value.strip()) for value in re.findall(r"<loc>\s*(.*?)\s*</loc>", body, re.I | re.S)]
+        raw_locs = [value.strip() for value in re.findall(r"<loc>\s*(.*?)\s*</loc>", body, re.I | re.S)]
+        for value in raw_locs:
+            if not re.match(r"^https?://[^\s]+$", value, re.I):
+                violations.append({"sitemap": sitemap_url, "loc": value, "reason": "sitemap loc must be an absolute HTTP(S) URL"})
+        locs = [urljoin(base + "/", value) for value in raw_locs]
         if re.search(r"<sitemapindex\b", body, re.I):
             pending.extend(locs)
         else:
             pages.extend(locs)
-    return list(dict.fromkeys(pages))
+    return list(dict.fromkeys(pages)), violations
 
 
 def main() -> int:
@@ -215,7 +220,8 @@ def main() -> int:
     crawl = {"enabled": args.crawl, "passed": True, "pages": []}
     if args.crawl:
         try:
-            urls = sitemap_urls(base)[: args.max_pages]
+            urls, sitemap_violations = sitemap_urls(base)
+            urls = urls[: args.max_pages]
             for page_url in urls:
                 try:
                     status, content_type, body = fetch(page_url)
@@ -232,7 +238,8 @@ def main() -> int:
                 except Exception as exc:
                     page_checks = {"url": page_url, "passed": False, "error": type(exc).__name__}
                 crawl["pages"].append(page_checks)
-            crawl["passed"] = bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
+            crawl["sitemap_loc_violations"] = sitemap_violations
+            crawl["passed"] = not sitemap_violations and bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
             crawl["url_count"] = len(urls)
         except Exception as exc:
             crawl = {"enabled": True, "passed": False, "error": type(exc).__name__, "pages": []}

package/bundled-tools/runtime/maggie_media.py

@@ -0,0 +1,144 @@
+"""Safe image inventory, responsive variant planning, and confirmation helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import mimetypes
+import re
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+
+
+IMAGE_TYPES = {".avif", ".gif", ".jpeg", ".jpg", ".png", ".webp"}
+SKIP_DIRS = {".git", ".maggie", "node_modules", "dist", "build", ".astro"}
+THIRD_PARTY_PROVIDERS = {"unsplash", "cloudinary"}
+
+
+def asset_id(value: str) -> str:
+    return "asset-" + hashlib.sha256(value.encode("utf-8")).hexdigest()[:16]
+
+
+def image_dimensions(path: Path) -> tuple[int | None, int | None]:
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return None, None
+    if data.startswith(b"\x89PNG\r\n\x1a\n") and len(data) >= 24:
+        return int.from_bytes(data[16:20], "big"), int.from_bytes(data[20:24], "big")
+    if data.startswith(b"RIFF") and data[8:12] == b"WEBP" and len(data) >= 30:
+        if data[12:16] == b"VP8X":
+            return 1 + int.from_bytes(data[24:27], "little"), 1 + int.from_bytes(data[27:30], "little")
+    if data.startswith(b"\xff\xd8"):
+        index = 2
+        while index + 9 < len(data):
+            if data[index] != 0xFF:
+                index += 1
+                continue
+            marker = data[index + 1]
+            index += 2
+            if marker in {0xD8, 0xD9}:
+                continue
+            length = int.from_bytes(data[index:index + 2], "big")
+            if marker in set(range(0xC0, 0xC4)) | set(range(0xC5, 0xC8)) | set(range(0xC9, 0xCC)) | set(range(0xCD, 0xD0)):
+                return int.from_bytes(data[index + 5:index + 7], "big"), int.from_bytes(data[index + 3:index + 5], "big")
+            index += length
+    return None, None
+
+
+def inventory_project(project: str | Path) -> dict[str, Any]:
+    root = Path(project).resolve()
+    assets = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or path.suffix.lower() not in IMAGE_TYPES or any(part in SKIP_DIRS for part in path.parts):
+            continue
+        relative = path.relative_to(root).as_posix()
+        width, height = image_dimensions(path)
+        assets.append({"assetId": asset_id(relative), "source": {"path": relative, "visibility": "public" if relative.startswith("public/") else "unknown"}, "mimeType": mimetypes.guess_type(path.name)[0] or "application/octet-stream", "bytes": path.stat().st_size, "intrinsic": {"width": width, "height": height}, "altText": {"status": "unknown"}})
+    return {"schemaVersion": "maggie-seo-image-inventory.v1", "assets": assets, "provenance": {"project": str(root), "redactions": ["absolute_project_path_in_public_reports"]}}
+
+
+def transform_third_party_url(url: str, provider: str, width: int) -> str:
+    if provider not in THIRD_PARTY_PROVIDERS:
+        raise ValueError("third-party provider is not allowlisted")
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("third-party source must be an absolute HTTP(S) URL")
+    if parsed.username or parsed.password or parsed.fragment:
+        raise ValueError("third-party source contains unsafe URL data")
+    if width < 1:
+        raise ValueError("variant width must be positive")
+    if provider == "unsplash":
+        query = dict(parse_qsl(parsed.query, keep_blank_values=True))
+        query.update({"w": str(width), "auto": "format"})
+        return urlunparse((parsed.scheme, parsed.netloc, parsed.path, parsed.params, urlencode(query), ""))
+    if "/upload/" not in parsed.path:
+        raise ValueError("cloudinary URL must contain an /upload/ segment")
+    path = parsed.path.replace("/upload/", f"/upload/w_{width},f_auto/", 1)
+    return urlunparse((parsed.scheme, parsed.netloc, path, parsed.params, parsed.query, ""))
+
+
+def plan_variants(inventory: dict[str, Any], widths: list[int], provider: str | None = None) -> dict[str, Any]:
+    if not widths or any(width < 1 for width in widths):
+        raise ValueError("widths must contain positive integers")
+    assets = []
+    for item in inventory.get("assets", []):
+        source = item.get("source", {})
+        source_url = source.get("url")
+        source_path = source.get("path")
+        variants = []
+        for width in sorted(set(widths)):
+            if source_url and provider:
+                url = transform_third_party_url(source_url, provider, width)
+                status = "planned"
+            elif source_path:
+                path = Path(source_path)
+                url = str(path.with_name(f"{path.stem}-{width}{path.suffix}"))
+                # Planning never confirms a derived file merely because the
+                # original has the same intrinsic width. Confirmation requires
+                # checking the candidate artifact itself.
+                status = "planned"
+            else:
+                continue
+            variants.append({"width": width, "format": Path(urlparse(url).path).suffix.lstrip(".") or "original", "url": url, "status": status, "evidence": {}})
+        assets.append({**item, "variants": variants, "markupPolicy": {"allowedWidths": [item["width"] for item in variants if item["status"] == "confirmed"], "missingVariantPolicy": "omit", "fetchPriority": "auto"}})
+    return {"schemaVersion": "maggie-seo-image-variants.v1", "manifestId": "images-" + hashlib.sha256(str(len(assets)).encode()).hexdigest()[:12], "createdAt": __import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat().replace("+00:00", "Z"), "assets": assets, "provenance": {"redactions": ["private_paths", "credentials"]}}
+
+
+def confirm_variants(manifest: dict[str, Any], checker: Callable[[str], int]) -> dict[str, Any]:
+    result = {**manifest, "assets": []}
+    for asset in manifest.get("assets", []):
+        updated = {**asset, "variants": []}
+        for variant in asset.get("variants", []):
+            candidate = {**variant}
+            if candidate.get("status") == "planned":
+                try:
+                    status = checker(candidate["url"])
+                    candidate["status"] = "confirmed" if status == 200 else "failed"
+                    candidate["evidence"] = {"status": status}
+                except Exception as exc:
+                    candidate["status"] = "failed"
+                    candidate["evidence"] = {"error": type(exc).__name__}
+            updated["variants"].append(candidate)
+        updated["markupPolicy"] = {**asset.get("markupPolicy", {}), "allowedWidths": [v["width"] for v in updated["variants"] if v.get("status") == "confirmed"]}
+        result["assets"].append(updated)
+    return result
+
+
+def confirmed_srcset(asset: dict[str, Any]) -> str:
+    return ", ".join(f"{variant['url']} {variant['width']}w" for variant in asset.get("variants", []) if variant.get("status") == "confirmed")
+
+
+def validate_manifest(manifest: dict[str, Any]) -> list[str]:
+    errors = []
+    for asset in manifest.get("assets", []):
+        for variant in asset.get("variants", []):
+            if variant.get("status") == "confirmed" and not variant.get("evidence"):
+                errors.append(f"confirmed variant lacks evidence: {asset.get('assetId')}")
+            if variant.get("status") == "confirmed" and not variant.get("url"):
+                errors.append(f"confirmed variant lacks URL: {asset.get('assetId')}")
+        allowed = set(asset.get("markupPolicy", {}).get("allowedWidths", []))
+        actual = {variant.get("width") for variant in asset.get("variants", []) if variant.get("status") == "confirmed"}
+        if allowed != actual:
+            errors.append(f"markup allowedWidths does not match confirmed variants: {asset.get('assetId')}")
+    return errors

package/bundled-tools/runtime/maggie_pagespeed.py

@@ -0,0 +1,213 @@
+"""Provider-neutral PageSpeed sampling, normalization, and comparison helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import statistics
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+from urllib.request import Request, urlopen
+
+
+METRICS = ("performanceScore", "lcp", "cls", "inp", "tbt", "fcp", "ttfb")
+STRATEGIES = ("desktop", "mobile")
+DEFAULT_THRESHOLDS = {
+    "performanceScore": {"direction": "decrease", "absolute": 0.05},
+    "lcp": {"direction": "increase", "relative": 0.10},
+    "cls": {"direction": "increase", "absolute": 0.05},
+    "inp": {"direction": "increase", "relative": 0.10},
+    "tbt": {"direction": "increase", "relative": 0.10},
+    "fcp": {"direction": "increase", "relative": 0.10},
+    "ttfb": {"direction": "increase", "relative": 0.10},
+}
+
+
+class PageSpeedError(RuntimeError):
+    """A safe, typed provider failure without credentials or response bodies."""
+
+    def __init__(self, kind: str, message: str) -> None:
+        self.kind = kind
+        super().__init__(message)
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def validate_public_url(value: str) -> str:
+    parsed = urlparse(value.strip())
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("URL must be an absolute HTTP(S) URL")
+    if parsed.username or parsed.password:
+        raise ValueError("URL must not contain credentials")
+    if parsed.fragment:
+        raise ValueError("URL must not contain a fragment")
+    return value.strip()
+
+
+def redact_url(value: str) -> str:
+    parsed = urlparse(value)
+    safe_query = [(key, "[redacted]") if re.search(r"token|key|secret|password", key, re.I) else (key, val) for key, val in parse_qsl(parsed.query, keep_blank_values=True)]
+    return urlunparse((parsed.scheme, parsed.netloc, parsed.path, parsed.params, urlencode(safe_query), ""))
+
+
+def _number(value: Any) -> float | None:
+    return float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+
+def _audit_number(audits: dict[str, Any], *names: str) -> float | None:
+    for name in names:
+        value = audits.get(name, {})
+        if isinstance(value, dict):
+            number = _number(value.get("numericValue"))
+            if number is not None:
+                return number
+    return None
+
+
+def _field_metric(metrics: dict[str, Any], *names: str) -> dict[str, Any]:
+    for name in names:
+        value = metrics.get(name)
+        if isinstance(value, dict):
+            percentile = _number(value.get("percentile"))
+            return {"value": percentile, "category": value.get("category"), "source": "field"}
+    return {"value": None, "source": "field", "status": "not_available"}
+
+
+def normalize_response(response: dict[str, Any], requested_url: str, strategy: str, sampled_at: str | None = None) -> dict[str, Any]:
+    lighthouse = response.get("lighthouseResult") or {}
+    audits = lighthouse.get("audits") if isinstance(lighthouse.get("audits"), dict) else {}
+    categories = lighthouse.get("categories") if isinstance(lighthouse.get("categories"), dict) else {}
+    performance = categories.get("performance") if isinstance(categories.get("performance"), dict) else {}
+    loading = response.get("loadingExperience") if isinstance(response.get("loadingExperience"), dict) else {}
+    field_metrics = loading.get("metrics") if isinstance(loading.get("metrics"), dict) else {}
+    lab = {
+        "performanceScore": _number(performance.get("score")),
+        "lcp": _audit_number(audits, "largest-contentful-paint"),
+        "cls": _audit_number(audits, "cumulative-layout-shift"),
+        "inp": _audit_number(audits, "interaction-to-next-paint", "experimental-interaction-to-next-paint"),
+        "tbt": _audit_number(audits, "total-blocking-time"),
+        "fcp": _audit_number(audits, "first-contentful-paint"),
+        "ttfb": _audit_number(audits, "server-response-time", "time-to-first-byte"),
+    }
+    field = {
+        "lcp": _field_metric(field_metrics, "LARGEST_CONTENTFUL_PAINT_MS"),
+        "cls": _field_metric(field_metrics, "CUMULATIVE_LAYOUT_SHIFT_SCORE"),
+        "inp": _field_metric(field_metrics, "INTERACTION_TO_NEXT_PAINT"),
+    }
+    return {
+        "requestedUrl": redact_url(requested_url),
+        "finalUrl": redact_url(str(lighthouse.get("finalUrl") or response.get("id") or requested_url)),
+        "strategy": strategy,
+        "sampledAt": sampled_at or now_iso(),
+        "fetchTime": lighthouse.get("fetchTime"),
+        "duplicateFetchTime": False,
+        "status": "ok",
+        "providerVersion": lighthouse.get("lighthouseVersion"),
+        "warnings": lighthouse.get("runWarnings") if isinstance(lighthouse.get("runWarnings"), list) else [],
+        "lab": lab,
+        "fieldData": {
+            "status": "available" if field_metrics else "not_available",
+            "source": "pagespeed-loading-experience",
+            "metrics": field,
+        },
+    }
+
+
+def fetch_pagespeed(url: str, strategy: str, categories: list[str] | None = None, locale: str | None = None, api_key: str | None = None, timeout: int = 45) -> dict[str, Any]:
+    validate_public_url(url)
+    if strategy not in STRATEGIES:
+        raise ValueError("strategy must be desktop or mobile")
+    query = {"url": url, "strategy": strategy}
+    for category in categories or ["performance"]:
+        query.setdefault("category", category)
+    if locale:
+        query["locale"] = locale
+    if api_key:
+        query["key"] = api_key
+    endpoint = "https://pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed?" + urlencode(query)
+    request = Request(endpoint, headers={"User-Agent": "Maggie-SEO-Performance/1.0", "Accept": "application/json"})
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            if response.status != 200:
+                raise PageSpeedError(f"http_{response.status}", f"PageSpeed returned HTTP {response.status}")
+            return json.loads(response.read(5_000_000).decode("utf-8"))
+    except PageSpeedError:
+        raise
+    except TimeoutError as exc:
+        raise PageSpeedError("timeout", "PageSpeed request timed out") from exc
+    except json.JSONDecodeError as exc:
+        raise PageSpeedError("invalid_json", "PageSpeed returned invalid JSON") from exc
+    except Exception as exc:
+        status = getattr(exc, "code", None)
+        if status:
+            raise PageSpeedError(f"http_{status}", f"PageSpeed returned HTTP {status}") from exc
+        raise PageSpeedError("network", f"PageSpeed request failed: {type(exc).__name__}") from exc
+
+
+def aggregate_samples(samples: list[dict[str, Any]], minimum: int = 3) -> dict[str, Any]:
+    independent = [sample for sample in samples if sample.get("status") == "ok" and not sample.get("duplicateFetchTime")]
+    aggregate: dict[str, Any] = {"independentSampleCount": len(independent), "status": "pass" if len(independent) >= minimum else "inconclusive", "metrics": {}}
+    for metric in METRICS:
+        values = [_number((sample.get("lab") or {}).get(metric)) for sample in independent]
+        values = [value for value in values if value is not None]
+        aggregate["metrics"][metric] = {"median": statistics.median(values) if values else None, "min": min(values) if values else None, "max": max(values) if values else None, "spread": max(values) - min(values) if values else None, "sampleCount": len(values), "status": "available" if values else "not_available"}
+    return aggregate
+
+
+def compare_aggregate(current: dict[str, Any], baseline: dict[str, Any] | None, thresholds: dict[str, dict[str, float]] | None = None) -> dict[str, Any]:
+    if not baseline:
+        return {"status": "no_baseline", "baselineId": None, "changes": [], "reasons": ["no baseline supplied"]}
+    if current.get("independentSampleCount", 0) < 3 or baseline.get("independentSampleCount", 0) < 3:
+        return {"status": "inconclusive", "baselineId": baseline.get("reportId"), "changes": [], "reasons": ["both current and baseline require at least three independent samples"]}
+    policy = thresholds or DEFAULT_THRESHOLDS
+    changes = []
+    for metric, rule in policy.items():
+        before = _number((baseline.get("metrics", {}).get(metric) or {}).get("median"))
+        after = _number((current.get("metrics", {}).get(metric) or {}).get("median"))
+        if before is None or after is None:
+            continue
+        delta = after - before
+        breach = delta <= -rule.get("absolute", float("inf")) if rule["direction"] == "decrease" and "absolute" in rule else delta >= rule.get("absolute", float("inf")) if rule["direction"] == "increase" and "absolute" in rule else (after <= before * (1 - rule.get("relative", 0)) if rule["direction"] == "decrease" else after >= before * (1 + rule.get("relative", 0)))
+        changes.append({"metric": metric, "before": before, "after": after, "delta": delta, "breach": bool(breach), "rule": rule})
+    breached = [change for change in changes if change["breach"]]
+    return {"status": "regression" if len(breached) >= 1 else "no_regression", "baselineId": baseline.get("reportId"), "changes": changes, "reasons": [f"{item['metric']} exceeded configured threshold" for item in breached]}
+
+
+def make_report(urls: list[str], strategies: list[str], samples: int, spacing_seconds: float, fetcher: Callable[[str, str], dict[str, Any]], baseline: dict[str, Any] | None = None, minimum: int = 3) -> dict[str, Any]:
+    pages = []
+    for url in urls:
+        validate_public_url(url)
+        for strategy in strategies:
+            records = []
+            seen_fetch_times: set[str] = set()
+            for index in range(samples):
+                if index and spacing_seconds:
+                    time.sleep(spacing_seconds)
+                try:
+                    record = normalize_response(fetcher(url, strategy), url, strategy)
+                    fetch_time = record.get("fetchTime")
+                    if fetch_time and fetch_time in seen_fetch_times:
+                        record["duplicateFetchTime"] = True
+                    elif fetch_time:
+                        seen_fetch_times.add(fetch_time)
+                except PageSpeedError as exc:
+                    record = {"requestedUrl": redact_url(url), "strategy": strategy, "sampledAt": now_iso(), "status": "error", "error": {"kind": exc.kind, "message": str(exc)}}
+                records.append(record)
+            aggregate = aggregate_samples(records, minimum)
+            baseline_page = None
+            if baseline:
+                baseline_page = next((item.get("aggregate") for item in baseline.get("pages", []) if item.get("requestedUrl") == redact_url(url) and item.get("strategy") == strategy), None)
+            pages.append({"requestedUrl": redact_url(url), "strategy": strategy, "samples": records, "aggregate": aggregate, "fieldData": {"status": "available" if any((item.get("fieldData") or {}).get("status") == "available" for item in records) else "not_available"}, "comparison": compare_aggregate(aggregate, baseline_page)})
+    statuses = [page["comparison"]["status"] for page in pages]
+    summary = "fail" if "regression" in statuses else "inconclusive" if any(status == "inconclusive" or page["aggregate"]["status"] == "inconclusive" for status, page in zip(statuses, pages)) else "pass"
+    return {"schemaVersion": "maggie-seo-performance.v1", "reportId": "perf-" + datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S"), "createdAt": now_iso(), "provider": "pagespeed-insights", "providerApiVersion": "v5", "policy": {"strategies": strategies, "requestedSamples": samples, "minimumIndependentSamples": minimum, "spacingSeconds": spacing_seconds, "duplicateFetchTimePolicy": "exclude"}, "pages": pages, "summary": {"status": summary}, "provenance": {"commands": [], "redactions": ["api_key", "credentialed_urls"]}}
+
+
+def load_json(path: str | Path) -> dict[str, Any]:
+    return json.loads(Path(path).read_text(encoding="utf-8"))

package/bundled-tools/runtime/maggie_sitemap.py

@@ -0,0 +1,131 @@
+"""Typed sitemap planning, chunking, validation, and redirect planning."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime, timezone
+from html import escape
+from urllib.parse import parse_qs, urlparse
+from xml.etree import ElementTree
+
+HARD_URL_LIMIT = 50_000
+HARD_BYTES_LIMIT = 52_428_800
+DEFAULT_CHUNK_TARGET = 500
+EXCLUDED_PATHS = re.compile(r"/(search|find|login|draft|preview)(/|$)", re.I)
+
+
+def absolute_url(url: str, origin: str) -> bool:
+    parsed = urlparse(url)
+    return parsed.scheme in {"http", "https"} and bool(parsed.netloc) and not parsed.fragment and parsed.netloc == urlparse(origin).netloc
+
+
+def parse_routes(text: str) -> list[dict[str, str]]:
+    routes = []
+    for line in text.splitlines():
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        parts = line.split("\t")
+        if len(parts) < 2:
+            raise ValueError("route lines must be type<TAB>absolute-url<TAB>optional-lastmod")
+        item = {"type": parts[0].strip(), "url": parts[1].strip()}
+        if len(parts) > 2 and parts[2].strip():
+            item["lastmod"] = parts[2].strip()
+        routes.append(item)
+    return routes
+
+
+def filter_routes(routes: list[dict[str, str]], origin: str, content_types: set[str]) -> tuple[dict[str, list[dict[str, str]]], list[dict[str, str]]]:
+    groups = {item: [] for item in sorted(content_types)}
+    excluded = []
+    for route in routes:
+        url = route.get("url", "")
+        parsed = urlparse(url)
+        reason = None
+        if route.get("type") not in content_types:
+            reason = "content type not enabled"
+        elif not absolute_url(url, origin):
+            reason = "URL must be an absolute HTTP(S) URL on the approved origin"
+        elif EXCLUDED_PATHS.search(parsed.path) or any(key in parse_qs(parsed.query) for key in ("q", "search", "filter", "page")):
+            reason = "search, filter, or non-canonical route"
+        elif route.get("type", "").lower() in {"rss", "atom", "feed"}:
+            reason = "feed is not an HTML sitemap entry"
+        if reason:
+            excluded.append({"url": url, "type": route.get("type", ""), "reason": reason})
+        else:
+            groups.setdefault(route["type"], []).append(route)
+    for key in groups:
+        groups[key] = list({item["url"]: item for item in groups[key]}.values())
+    return groups, excluded
+
+
+def xml_file(urls: list[dict[str, str]]) -> str:
+    rows = []
+    for item in urls:
+        lastmod = f"<lastmod>{escape(item['lastmod'])}</lastmod>" if item.get("lastmod") else ""
+        rows.append(f"<url><loc>{escape(item['url'])}</loc>{lastmod}</url>")
+    return '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">' + "".join(rows) + "</urlset>\n"
+
+
+def build_plan(routes: list[dict[str, str]], origin: str, content_types: set[str], chunk_target: int = DEFAULT_CHUNK_TARGET, previous: dict | None = None) -> dict:
+    if chunk_target < 1 or chunk_target > HARD_URL_LIMIT:
+        raise ValueError("chunk target must be between 1 and 50000")
+    groups, excluded = filter_routes(routes, origin, content_types)
+    group_plans = []
+    sitemap_urls = []
+    for content_type in sorted(content_types):
+        chunks = []
+        entries = groups.get(content_type, []) or []
+        for index in range(0, max(len(entries), 1), chunk_target):
+            chunk_entries = entries[index:index + chunk_target]
+            filename = f"sitemap-{content_type}-{index // chunk_target + 1}.xml"
+            xml = xml_file(chunk_entries)
+            url = origin.rstrip("/") + "/" + filename
+            chunks.append({"filename": filename, "url": url, "entries": len(chunk_entries), "bytes": len(xml.encode()), "sha256": hashlib.sha256(xml.encode()).hexdigest(), "xml": xml})
+            sitemap_urls.append(url)
+        group_plans.append({"contentType": content_type, "chunks": chunks})
+    index_xml = '<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">' + "".join(f"<sitemap><loc>{escape(url)}</loc></sitemap>" for url in sitemap_urls) + "</sitemapindex>\n"
+    current = set(sitemap_urls)
+    old = set((previous or {}).get("sitemapUrls", []))
+    redirects = [{"from": url, "to": origin.rstrip("/") + "/sitemap.xml", "reason": "previously advertised sitemap removed"} for url in sorted(old - current)]
+    plan = {"schemaVersion": "maggie-seo-sitemap-plan.v1", "planId": "sitemap-" + datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S"), "origin": origin.rstrip("/"), "groups": group_plans, "index": {"url": origin.rstrip("/") + "/sitemap.xml", "bytes": len(index_xml.encode()), "xml": index_xml, "sitemapUrls": sitemap_urls}, "redirects": redirects, "excluded": excluded}
+    plan["validation"] = validate_plan_data(plan)
+    return plan
+
+
+def validate_plan_data(plan: dict) -> dict:
+    errors = []
+    warnings = []
+    origin = plan.get("origin", "")
+    if not urlparse(origin).scheme or not urlparse(origin).netloc:
+        errors.append("origin must be an absolute HTTP(S) URL")
+    expected_urls = []
+    for group in plan.get("groups", []):
+        for chunk in group.get("chunks", []):
+            expected_urls.append(chunk.get("url"))
+            if chunk.get("entries", 0) > HARD_URL_LIMIT:
+                errors.append(f"chunk exceeds URL limit: {chunk.get('filename')}")
+            if chunk.get("bytes", 0) > HARD_BYTES_LIMIT:
+                errors.append(f"chunk exceeds byte limit: {chunk.get('filename')}")
+            try:
+                root = ElementTree.fromstring(chunk.get("xml", ""))
+                locs = [element.text or "" for element in root.iter() if element.tag.endswith("loc")]
+                if any(not absolute_url(value, origin) for value in locs):
+                    errors.append(f"chunk contains a relative or off-origin loc: {chunk.get('filename')}")
+            except ElementTree.ParseError:
+                errors.append(f"chunk is not valid XML: {chunk.get('filename')}")
+    index = plan.get("index", {})
+    if index.get("bytes", 0) > HARD_BYTES_LIMIT:
+        errors.append("sitemap index exceeds byte limit")
+    try:
+        index_root = ElementTree.fromstring(index.get("xml", ""))
+        index_locs = [element.text or "" for element in index_root.iter() if element.tag.endswith("loc")]
+        if any(not absolute_url(value, origin) for value in index_locs):
+            errors.append("sitemap index contains a relative or off-origin loc")
+        if set(index_locs) != set(expected_urls):
+            errors.append("sitemap index references do not match generated chunks")
+    except ElementTree.ParseError:
+        errors.append("sitemap index is not valid XML")
+    if not expected_urls:
+        warnings.append("no sitemap chunks generated")
+    return {"status": "pass" if not errors else "fail", "errors": errors, "warnings": warnings}

package/package.json

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