@topy-ai/maggie 0.7.0 → 0.7.2

package/bundled-tools/clis/maggie_dash.py

@@ -11,12 +11,18 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
+import shutil
+import subprocess
 import sys
+import tempfile
+from datetime import datetime, timezone
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from maggie_dash_store import MaggieDashStore  # noqa: E402
 from service_variants import ServiceVariantStore  # noqa: E402
+from maggie_dash_ui import load_and_validate  # noqa: E402
 
 
 def project_root(args: argparse.Namespace) -> Path:
@@ -37,6 +43,118 @@ def require_confirm(args: argparse.Namespace) -> None:
         raise SystemExit(2)
 
 
+DEFAULT_DASH_SOURCE = "https://github.com/TOPY-AI-LTD/MaggieDash.git"
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def git_revision(path: Path) -> str | None:
+    try:
+        result = subprocess.run(["git", "-C", str(path), "rev-parse", "HEAD"], capture_output=True, text=True, check=True)
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    return result.stdout.strip() or None
+
+
+def copy_dashboard_tree(source: Path, target: Path, force: bool) -> tuple[list[str], list[str]]:
+    installed: list[str] = []
+    preserved: list[str] = []
+    target.mkdir(parents=True, exist_ok=True)
+    for path in sorted(source.rglob("*")):
+        relative = path.relative_to(source)
+        destination = target / relative
+        if path.is_dir():
+            destination.mkdir(parents=True, exist_ok=True)
+            continue
+        if destination.exists() and not force:
+            preserved.append(str(destination))
+            continue
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, destination)
+        installed.append(str(destination))
+    return installed, preserved
+
+
+def command_install(args: argparse.Namespace) -> int:
+    require_confirm(args)
+    root = project_root(args)
+    source_value = args.source or os.environ.get("MAGGIE_DASH_SOURCE") or DEFAULT_DASH_SOURCE
+    ref = args.ref
+    target = root / args.target
+    temporary: tempfile.TemporaryDirectory[str] | None = None
+    source = Path(source_value).expanduser().resolve() if not source_value.startswith(("https://", "http://", "git@")) else None
+    try:
+        if source is None:
+            temporary = tempfile.TemporaryDirectory(prefix="maggiedash-install-")
+            clone = ["git", "clone", "--depth", "1"]
+            if ref:
+                clone.extend(["--branch", ref])
+            clone.extend([source_value, temporary.name])
+            result = subprocess.run(clone, capture_output=True, text=True)
+            if result.returncode:
+                detail = (result.stderr or result.stdout).strip().splitlines()[-1:]
+                raise RuntimeError("MaggieDash source could not be cloned" + (f": {detail[0]}" if detail else ""))
+            source = Path(temporary.name)
+        if not source.is_dir():
+            raise RuntimeError(f"MaggieDash source directory not found: {source}")
+        manifest_path = source / "maggiedash.json"
+        if not manifest_path.exists():
+            raise RuntimeError("MaggieDash source has no maggiedash.json manifest")
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        if manifest.get("schemaVersion") != "maggiedash-distribution.v1":
+            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")
+        installed: list[str] = []
+        preserved: list[str] = []
+        for item in manifest.get("files", []):
+            relative = Path(item)
+            if relative.is_absolute() or ".." in relative.parts:
+                raise RuntimeError(f"unsafe MaggieDash manifest path: {item}")
+            source_item = source / relative
+            if not source_item.exists():
+                raise RuntimeError(f"MaggieDash manifest file is missing: {item}")
+            if relative.parts and relative.parts[0] == "admin":
+                destination = target / Path(*relative.parts[1:])
+            else:
+                destination = target / relative
+            if source_item.is_dir():
+                current_installed, current_preserved = copy_dashboard_tree(source_item, destination, args.force)
+            else:
+                current_installed = []
+                current_preserved = []
+                if destination.exists() and not args.force:
+                    current_preserved = [str(destination)]
+                else:
+                    destination.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(source_item, destination)
+                    current_installed = [str(destination)]
+            installed.extend(current_installed)
+            preserved.extend(current_preserved)
+        state = {
+            "schemaVersion": "maggiedash-install.v1",
+            "status": "installed",
+            "source": source_value,
+            "ref": ref,
+            "revision": git_revision(source),
+            "version": manifest.get("version"),
+            "target": str(target),
+            "installed": sorted(set(installed)),
+            "preserved": sorted(set(preserved)),
+            "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
+    finally:
+        if temporary is not None:
+            temporary.cleanup()
+
+
 def command_init(args: argparse.Namespace) -> int:
     require_confirm(args)
     root = project_root(args)
@@ -93,6 +211,38 @@ def command_transition(args: argparse.Namespace) -> int:
         store.close()
 
 
+def command_cms(args: argparse.Namespace) -> int:
+    require_confirm(args)
+    store = store_for(project_root(args))
+    try:
+        if args.cms_command == "revisions":
+            result = store.list_revisions(args.project_id, args.document_id)
+        elif args.cms_command == "trash":
+            result = store.trash(args.project_id, args.document_id, args.actor, args.reason)
+        elif args.cms_command == "restore":
+            result = store.restore(args.project_id, args.document_id, args.actor, args.reason)
+        elif args.cms_command == "schedule":
+            result = store.schedule_publish(args.project_id, args.document_id, args.publish_at, args.actor, args.reason)
+        elif args.cms_command == "duplicate":
+            result = store.duplicate(args.project_id, args.document_id, args.new_id, args.new_slug, args.actor, args.reason)
+        elif args.cms_command == "redirect":
+            result = store.add_redirect(args.project_id, args.from_path, args.to_path, args.actor, args.reason, args.status_code)
+        elif args.cms_command == "preview":
+            result = store.issue_preview(args.project_id, args.document_id, args.secret, args.ttl)
+        else:
+            raise ValueError(f"unknown CMS command: {args.cms_command}")
+        emit(result)
+        return 0
+    finally:
+        store.close()
+
+
+def command_ui(args: argparse.Namespace) -> int:
+    result = load_and_validate(Path(args.contract).resolve(), [Path(value).resolve() for value in args.source])
+    emit(result)
+    return 0 if result["passed"] else 1
+
+
 def variant_store(args: argparse.Namespace) -> ServiceVariantStore:
     return ServiceVariantStore(project_root(args) / ".maggie" / "service-variants.json")
 
@@ -138,6 +288,14 @@ def parser() -> argparse.ArgumentParser:
     init.add_argument("--locale", default="en-GB")
     init.add_argument("--confirm", action="store_true")
     init.set_defaults(func=command_init)
+    install = sub.add_parser("install", help="install the MaggieDash admin workspace")
+    install.add_argument("--project", default=".")
+    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("--force", action="store_true", help="replace existing dashboard files")
+    install.add_argument("--confirm", action="store_true")
+    install.set_defaults(func=command_install)
     status = sub.add_parser("status", help="inspect project and documents")
     status.add_argument("--project", default=".")
     status.add_argument("--project-id", default="local-project")
@@ -155,6 +313,27 @@ def parser() -> argparse.ArgumentParser:
     transition.add_argument("--reason", required=True)
     transition.add_argument("--confirm", action="store_true")
     transition.set_defaults(func=command_transition)
+    cms = sub.add_parser("cms", help="manage revisions, trash, scheduling, redirects and previews")
+    cms_sub = cms.add_subparsers(dest="cms_command", required=True)
+    for name in ("revisions", "trash", "restore"):
+        command = cms_sub.add_parser(name)
+        command.add_argument("--project", default="."); command.add_argument("--project-id", default="local-project")
+        command.add_argument("--document-id", required=True); command.add_argument("--actor", default="cli"); command.add_argument("--reason", default="CMS operation"); command.add_argument("--confirm", action="store_true")
+    schedule = cms_sub.add_parser("schedule")
+    schedule.add_argument("--project", default="."); schedule.add_argument("--project-id", default="local-project"); schedule.add_argument("--document-id", required=True); schedule.add_argument("--publish-at", required=True); schedule.add_argument("--actor", default="cli"); schedule.add_argument("--reason", required=True); schedule.add_argument("--confirm", action="store_true")
+    duplicate = cms_sub.add_parser("duplicate")
+    duplicate.add_argument("--project", default="."); duplicate.add_argument("--project-id", default="local-project"); duplicate.add_argument("--document-id", required=True); duplicate.add_argument("--new-id", required=True); duplicate.add_argument("--new-slug", required=True); duplicate.add_argument("--actor", default="cli"); duplicate.add_argument("--reason", required=True); duplicate.add_argument("--confirm", action="store_true")
+    redirect = cms_sub.add_parser("redirect")
+    redirect.add_argument("--project", default="."); redirect.add_argument("--project-id", default="local-project"); redirect.add_argument("--from-path", required=True); redirect.add_argument("--to-path", required=True); redirect.add_argument("--status-code", type=int, default=301); redirect.add_argument("--actor", default="cli"); redirect.add_argument("--reason", required=True); redirect.add_argument("--confirm", action="store_true")
+    preview = cms_sub.add_parser("preview")
+    preview.add_argument("--project", default="."); preview.add_argument("--project-id", default="local-project"); preview.add_argument("--document-id", required=True); preview.add_argument("--secret", required=True); preview.add_argument("--ttl", type=int, default=900); preview.add_argument("--confirm", action="store_true")
+    cms.set_defaults(func=command_cms)
+    ui = sub.add_parser("ui", help="validate MaggieDash dashboard chrome")
+    ui_sub = ui.add_subparsers(dest="ui_command", required=True)
+    ui_validate = ui_sub.add_parser("validate")
+    ui_validate.add_argument("--contract", required=True)
+    ui_validate.add_argument("--source", action="append", default=[])
+    ui_validate.set_defaults(func=command_ui)
     variant = sub.add_parser("variant", help="manage service variant lifecycle")
     variant_sub = variant.add_subparsers(dest="variant_command", required=True)
     create = variant_sub.add_parser("create"); create.add_argument("--project", default="."); create.add_argument("--service-id", required=True); create.add_argument("--variant-id", required=True); create.add_argument("--variant-type", required=True); create.add_argument("--locale", required=True); create.add_argument("--market", required=True); create.add_argument("--slug", required=True); create.add_argument("--title", required=True); create.add_argument("--facts", required=True); create.add_argument("--source-revision", required=True); create.add_argument("--canonical-variant-id"); create.add_argument("--cluster-link", action="append", default=[]); create.add_argument("--layout-family", default="service-default"); create.add_argument("--confirm", action="store_true")

package/bundled-tools/clis/maggie_deployment.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import json
 import re
+import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -106,6 +107,7 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> di
             "restart": f"systemctl restart {service}",
             "verify": f"systemctl is-active {service} && curl -fsS https://{domain}/robots.txt && curl -fsS https://{domain}/sitemap.xml",
             "rollback": f"ln -sfn {root}/releases/<previous-release> {current} && systemctl restart {service}",
+            "data_rollback": "restore the matching data checkpoint before restarting the previous code release",
         },
         "files": {
             "systemd": f"{service}.service",
@@ -130,10 +132,36 @@ def validate_data_checkpoint(path: Path) -> dict:
     if isinstance(required, list) and isinstance(current, dict):
         missing = [table for table in required if table not in current]
         if missing: errors.append("currentCounts is missing required tables")
+        empty = [table for table in required if table in current and (not isinstance(current[table], int) or current[table] <= 0)]
+        if empty: errors.append("currentCounts has empty required tables: " + ", ".join(empty))
     if not value.get("release") or not value.get("checkedAt"): errors.append("release and checkedAt are required")
+    rollback = value.get("rollback")
+    if not isinstance(rollback, dict) or not rollback.get("backupId") or not rollback.get("restoreCommand"):
+        errors.append("rollback.backupId and rollback.restoreCommand are required for data rollback")
     return {"passed": not errors, "declared": True, "errors": errors}
 
 
+def validate_scheduler_request(method: str, origin: str | None, has_auth: bool) -> dict:
+    errors = []
+    if method.upper() == "POST":
+        if not origin or not re.fullmatch(r"https?://[^/\s]+", origin): errors.append("POST scheduler requests require an explicit Origin header")
+        if not has_auth: errors.append("POST scheduler requests require the configured auth contract")
+    return {"schemaVersion": "maggie-deployment-request.v1", "method": method.upper(), "originPresent": bool(origin), "authPresent": bool(has_auth), "passed": not errors, "errors": errors}
+
+
+def verify_infrastructure(units_dir: Path | None, service: str, timer: str | None = None) -> dict:
+    timer_name = timer or f"maggie-{service}.timer"
+    service_name = f"maggie-{service}.service" if not service.endswith(".service") else service
+    declared = bool(units_dir and (units_dir / service_name).is_file() and (units_dir / timer_name).is_file())
+    systemd = {"service": False, "timer": False}
+    for unit, key in ((service_name, "service"), (timer_name, "timer")):
+        try:
+            systemd[key] = subprocess.run(["systemctl", "is-enabled", unit], capture_output=True, text=True, check=False, timeout=5).returncode == 0
+        except (OSError, subprocess.SubprocessError):
+            systemd[key] = False
+    return {"schemaVersion": "maggie-deployment-infra.v1", "service": service_name, "timer": timer_name, "declaredArtifacts": declared, "systemdEnabled": systemd, "passed": declared or all(systemd.values()), "errors": [] if declared or all(systemd.values()) else ["systemd service/timer are not declared or enabled"]}
+
+
 def retention_plan(release_root: str, current_link: str, keep: int) -> dict:
     if keep < 2 or keep > 5:
         raise ValueError("keep must be between 2 and 5")
@@ -206,6 +234,13 @@ def main() -> int:
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
     parser.add_argument("--current-link", help="current symlink for --retention-plan")
     parser.add_argument("--keep-releases", type=int, default=2)
+    parser.add_argument("--verify-infra", action="store_true", help="verify declared or installed systemd service/timer")
+    parser.add_argument("--units-dir", help="directory containing generated .service and .timer units")
+    parser.add_argument("--timer", help="systemd timer unit name")
+    parser.add_argument("--validate-request", action="store_true", help="validate a scheduler request contract")
+    parser.add_argument("--method", default="POST")
+    parser.add_argument("--origin")
+    parser.add_argument("--has-auth", action="store_true")
     args = parser.parse_args()
     try:
         if args.vps_plan:
@@ -226,6 +261,14 @@ def main() -> int:
                 output.write_text(json.dumps(plan, indent=2) + "\n", encoding="utf-8")
             print(json.dumps(plan, indent=2, ensure_ascii=False))
             return 0
+        if args.validate_request:
+            result = validate_scheduler_request(args.method, args.origin, args.has_auth)
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+            return 0 if result["passed"] else 1
+        if args.verify_infra:
+            result = verify_infrastructure(Path(args.units_dir).resolve() if args.units_dir else None, args.service, args.timer)
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+            return 0 if result["passed"] else 1
         result = preflight(Path(args.project).resolve(), args.target, args.environment)
         if args.output:
             Path(args.output).parent.mkdir(parents=True, exist_ok=True)

package/bundled-tools/clis/maggie_feedback.py

@@ -34,6 +34,21 @@ def project_fingerprint(project: Path) -> str:
     return hashlib.sha256(str(project.resolve()).encode()).hexdigest()[:16]
 
 
+def installed_version(project: Path) -> str:
+    """Resolve the version from the runtime wrapper or project install state."""
+    if os.environ.get("MAGGIE_VERSION"):
+        return safe_text(os.environ["MAGGIE_VERSION"])
+    for path in (project / ".maggie" / "install.json", project / "VERSION"):
+        try:
+            value = json.loads(path.read_text(encoding="utf-8")) if path.suffix == ".json" else path.read_text(encoding="utf-8").strip()
+            if isinstance(value, dict): value = value.get("version", "")
+            if re.fullmatch(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?", str(value)):
+                return str(value)
+        except (OSError, ValueError, json.JSONDecodeError):
+            continue
+    return "unknown"
+
+
 def feedback_id(project: Path) -> str:
     timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
     return f"fb-{timestamp}-{project_fingerprint(project)[:6]}-{secrets.token_hex(3)}"
@@ -68,7 +83,7 @@ def collect(args: argparse.Namespace) -> int:
         "feedbackId": feedback_id(project),
         "createdAt": now(),
         "source": "maggie-cli",
-        "maggieVersion": os.environ.get("MAGGIE_VERSION", "unknown"),
+        "maggieVersion": installed_version(project),
         "type": args.type,
         "skill": skill,
         "runId": run_id,

package/bundled-tools/clis/maggie_ops.py

@@ -9,6 +9,10 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from dependency_lock import audit as audit_lockfiles
+from seed_evidence import validate_manifest
+
 
 REQUIRED_ROUTES = (
     "/ops", "/ops/posts", "/ops/sitemap", "/ops/reports",
@@ -132,14 +136,30 @@ def command_verify(args: argparse.Namespace) -> int:
     return 0 if result["checks"]["ready"] and result["stateFile"] else 1
 
 
+def command_lockfiles(args: argparse.Namespace) -> int:
+    result = audit_lockfiles(root(args))
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
+def command_seed_manifest(args: argparse.Namespace) -> int:
+    value = read_json(Path(args.manifest).resolve())
+    result = validate_manifest(value)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--project", default=".")
     sub = parser.add_subparsers(dest="command", required=True)
-    for name, handler in (("audit", command_audit), ("preflight", command_preflight), ("status", command_status), ("verify", command_verify)):
+    for name, handler in (("audit", command_audit), ("preflight", command_preflight), ("status", command_status), ("verify", command_verify), ("lockfiles", command_lockfiles)):
         command = sub.add_parser(name)
         if name == "preflight": command.add_argument("--write", action="store_true")
         command.set_defaults(func=handler)
+    seed = sub.add_parser("seed-manifest", help="validate explicit sanitized development fixtures")
+    seed.add_argument("--manifest", required=True)
+    seed.set_defaults(func=command_seed_manifest)
     record = sub.add_parser("record", help="record an explicitly authorised operation")
     record.add_argument("operation", choices=("sync", "sitemap-match", "rewrite-queue", "rewrite-approve", "publish", "migration"))
     record.add_argument("--dry-run", action="store_true")

package/bundled-tools/clis/maggie_service_booking.py

@@ -10,6 +10,9 @@ from pathlib import Path
 from urllib.parse import quote, urljoin, urlsplit
 from urllib.request import Request, urlopen
 
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from route_imports import imported_components  # noqa: E402
+
 NOW = lambda: datetime.now(timezone.utc).isoformat()
 MONEY = re.compile(r"(?:£|GBP\s*)\s*([0-9]+(?:[.,][0-9]{1,2})?)", re.I)
 DURATION = re.compile(r"(\d{2,3})\s*(?:min|mins|minutes?)", re.I)
@@ -751,7 +754,7 @@ def inventory_candidates(project, pages_root):
     found={}
     for page in pages_root.rglob("*") if pages_root.exists() else []:
         if page.is_file() and page.suffix.lower() in {".astro",".md",".mdx",".html"} and page.stem not in {"index","404"}:
-            found["/"+str(page.relative_to(project)).replace("\\","/")]={"path":"/"+str(page.relative_to(project)).replace("\\","/"),"text":page_text(page),"canonical":None,"pageType":"filesystem"}
+            found["/"+str(page.relative_to(project)).replace("\\","/")]={"path":"/"+str(page.relative_to(project)).replace("\\","/"),"text":page_text(page),"canonical":None,"pageType":"filesystem","imports":imported_components(page)}
     for name in ("pages.json","page-content.json"):
         source=project/"docs"/name
         if not source.exists(): continue
@@ -762,7 +765,7 @@ def inventory_candidates(project, pages_root):
             if not isinstance(item,dict): continue
             value=item.get("path") or item.get("url") or item.get("route")
             if not value: continue
-            current=found.setdefault(value,{"path":value,"text":"","canonical":None,"pageType":"inventory"}); current["text"]+=" "+str(item.get("content") or item.get("text") or item.get("title") or ""); current["canonical"]=item.get("canonicalUrl") or item.get("canonical") or current["canonical"]; current["pageType"]=item.get("pageType") or current["pageType"]
+            current=found.setdefault(value,{"path":value,"text":"","canonical":None,"pageType":"inventory","imports":[]}); current["text"]+=" "+str(item.get("content") or item.get("text") or item.get("title") or ""); current["canonical"]=item.get("canonicalUrl") or item.get("canonical") or current["canonical"]; current["pageType"]=item.get("pageType") or current["pageType"]
     return list(found.values())
 def cmd_match_pages_review(args):
     project=root(args); data=load(project); candidates=inventory_candidates(project,(project/args.pages_dir).resolve()); aliases={"lymphatic drainage":{"lymphatic","lymph drainage","lymphdrainage","manual lymphatic","ml d"},"deep tissue":{"deep tissue","therapeutic massage"},"thai":{"thai massage","thai"},"postpartum":{"postpartum","new mom"},"facial":{"facial","hydra facial","hydrafacial"},"massage":{"massage"}}
@@ -779,7 +782,7 @@ def cmd_match_pages_review(args):
         matches=[]
         for page in candidates:
             path_slug=slug(page["path"].rsplit("/",1)[-1].rsplit(".",1)[0]); page_words=page_tokens(path_slug+" "+page["text"][:2000]); exact=path_slug==service.get("slug"); overlap=len(expanded & page_words)/max(1,len(expanded)); generic=bool(concepts & {"massage","facial","acupuncture","waxing"}) and overlap<0.75; score=1.0 if exact else min(0.49 if generic else overlap,0.99)
-            if score>=0.45: matches.append({"path":page["path"],"role":"supporting","pageType":page["pageType"],"canonicalUrl":page["canonical"],"matchedConcepts":sorted(expanded & page_words),"method":"slug" if exact else "semantic-concepts","confidence":round(score,3)})
+            if score>=0.45: matches.append({"path":page["path"],"role":"supporting","pageType":page["pageType"],"canonicalUrl":page["canonical"],"matchedConcepts":sorted(expanded & page_words),"imports":page.get("imports",[]),"method":"slug" if exact else "semantic-concepts","confidence":round(score,3)})
         matches.sort(key=lambda x:(-x["confidence"],x["path"])); report.append({"serviceId":service["id"],"title":service["title"],"candidates":matches})
         for path_value in selections.get(service["id"], []):
             if path_value in {m["path"] for m in matches}: selected.append((service,path_value))

package/bundled-tools/clis/maggie_sitemap.py

@@ -10,7 +10,7 @@ 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
+from maggie_sitemap import agent_files, build_plan, parse_routes, validate_plan_data  # noqa: E402
 
 
 def write_json(path: str, value: dict) -> None:
@@ -31,6 +31,12 @@ def main() -> int:
     plan.add_argument("--output", required=True)
     validate = sub.add_parser("validate")
     validate.add_argument("--plan", required=True)
+    validate.add_argument("--strict-semantic", action="store_true")
+    agent = sub.add_parser("agent-files")
+    agent.add_argument("--origin", required=True)
+    agent.add_argument("--routes-file", required=True)
+    agent.add_argument("--output-dir", required=True)
+    agent.add_argument("--locale", default="en")
     apply = sub.add_parser("apply")
     apply.add_argument("--plan", required=True)
     apply.add_argument("--public-dir", required=True)
@@ -65,9 +71,17 @@ def main() -> int:
                     restored += 1
             print(json.dumps({"status": "rolled-back", "restored": restored}, indent=2))
             return 0
+        if args.command == "agent-files":
+            output = Path(args.output_dir)
+            output.mkdir(parents=True, exist_ok=True)
+            files = agent_files(parse_routes(Path(args.routes_file).read_text(encoding="utf-8")), args.origin, args.locale)
+            for name, content in files.items():
+                (output / name).write_text(content, encoding="utf-8")
+            print(json.dumps({"status": "generated", "locale": args.locale, "files": [str(output / name) for name in files]}, 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)
+            result = validate_plan_data(plan_value, args.strict_semantic)
             print(json.dumps(result, indent=2))
             return 0 if result["status"] == "pass" else 1
         if not args.confirm:

package/bundled-tools/runtime/analytics_traffic.py

@@ -0,0 +1,30 @@
+"""Safe classification of known first-party/toolchain traffic."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from typing import Iterable
+
+TOOL_USER_AGENT = re.compile(r"(?:maggie|playwright|puppeteer|selenium|lighthouse|headlesschrome|synthetic|test[-_ ]?sweep)", re.I)
+
+
+def is_tool_traffic(event: dict) -> bool:
+    if str(event.get("maggieTest") or "").lower() == "true":
+        return True
+    if str(event.get("xMaggieTest") or "").lower() == "true":
+        return True
+    return bool(TOOL_USER_AGENT.search(str(event.get("userAgent") or "")))
+
+
+def audit_events(events: Iterable[dict]) -> dict:
+    totals = Counter()
+    excluded = Counter()
+    included = 0
+    for event in events:
+        totals[str(event.get("event") or "unknown")] += 1
+        if is_tool_traffic(event):
+            excluded[str(event.get("event") or "unknown")] += 1
+        else:
+            included += 1
+    return {"schemaVersion": "maggie-analytics-traffic.v1", "total": sum(totals.values()), "included": included, "excluded": sum(excluded.values()), "byEvent": dict(sorted(totals.items())), "excludedByEvent": dict(sorted(excluded.items())), "policy": "exclude only explicit Maggie/toolchain markers; no IP or identity inference"}

package/bundled-tools/runtime/content_localization.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import re
-from typing import Any
+from typing import Any, Iterable
 
 # Deliberately broad, dependency-free registry of the major web/content
 # languages. Script variants remain distinct where they affect copy, search,
@@ -19,6 +19,68 @@ OPERATIONS = {"translate", "polish", "rewrite", "localise", "rebrand", "manual_e
 PROTECTED_FIELDS = {"price", "currency", "rating", "provider", "providerId", "bookingUrl", "paymentUrl", "legalClaims", "healthClaims", "contentId", "slug", "canonicalUrl", "translationGroupId"}
 
 
+class TranslationIndex:
+    """One canonical index for translated records and their public wording.
+
+    Hosts may persist this structure wherever they keep content, but they must
+    build it once and reject conflicting duplicate `(contentId, locale)` rows.
+    This prevents a registry and a second dictionary from silently disagreeing.
+    """
+
+    def __init__(self, records: Iterable[dict[str, Any]] = ()):
+        self._records: dict[tuple[str, str], dict[str, Any]] = {}
+        self.conflicts: list[dict[str, Any]] = []
+        for record in records:
+            self.add(record)
+
+    def add(self, record: dict[str, Any]) -> None:
+        content_id = str(record.get("contentId") or "").strip()
+        locale = str(record.get("locale") or "").strip()
+        if not content_id or not locale:
+            raise ValueError("translation index records require contentId and locale")
+        key = (content_id, locale)
+        previous = self._records.get(key)
+        if previous and previous != record:
+            self.conflicts.append({"key": key, "existing": previous, "incoming": record})
+            raise ValueError(f"conflicting translation record for {content_id}/{locale}")
+        self._records[key] = dict(record)
+
+    def get(self, content_id: str, locale: str) -> dict[str, Any] | None:
+        record = self._records.get((content_id, locale))
+        return dict(record) if record else None
+
+    def records(self) -> list[dict[str, Any]]:
+        return [dict(self._records[key]) for key in sorted(self._records)]
+
+    def as_dict(self) -> dict[str, dict[str, Any]]:
+        return {f"{content_id}:{locale}": dict(record) for (content_id, locale), record in sorted(self._records.items())}
+
+
+def is_translated_path(path: str, exact_paths: Iterable[str] = (), prefixes: Iterable[str] = ()) -> bool:
+    """Use exact routes and normalized prefix routes with identical semantics."""
+    normalized = "/" + str(path or "").lstrip("/")
+    normalized = normalized.rstrip("/") or "/"
+    exact = {("/" + str(item).lstrip("/")).rstrip("/") or "/" for item in exact_paths}
+    normalized_prefixes = {("/" + str(item).lstrip("/")).rstrip("/") or "/" for item in prefixes}
+    return normalized in exact or any(normalized == prefix or normalized.startswith(prefix + "/") for prefix in normalized_prefixes)
+
+
+def should_localize_path(path: str, locale_prefixes: Iterable[str], static_extensions: Iterable[str] = (".txt", ".md", ".xml", ".json")) -> bool:
+    """Locale middleware only handles localized routes, never root static files."""
+    normalized = "/" + str(path or "").lstrip("/")
+    if any(normalized.lower().endswith(extension.lower()) for extension in static_extensions):
+        return False
+    return is_translated_path(normalized, prefixes=locale_prefixes)
+
+
+def rewrite_once(request_key: str, seen: set[str]) -> bool:
+    """Return true only for the first rewrite observation of a request."""
+    if request_key in seen:
+        return False
+    seen.add(request_key)
+    return True
+
+
 def parse_locale(value: Any) -> tuple[str | None, str | None, str | None]:
     if not isinstance(value, str):
         return None, None, None

package/bundled-tools/runtime/dependency_lock.py

@@ -0,0 +1,43 @@
+"""Detect package-manager drift before an npm-ci deployment."""
+from __future__ import annotations
+import json
+import re
+from pathlib import Path
+
+
+def package_dependencies(project: Path) -> set[str]:
+    data = json.loads((project / "package.json").read_text(encoding="utf-8"))
+    return set(data.get("dependencies", {})) | set(data.get("devDependencies", {})) | set(data.get("optionalDependencies", {}))
+
+
+def npm_lock_dependencies(path: Path) -> set[str]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    packages = data.get("packages", {})
+    names = {key.removeprefix("node_modules/") for key in packages
+             if key.startswith("node_modules/") and "/node_modules/" not in key}
+    if not packages and isinstance(data.get("dependencies"), dict):
+        names = set(data["dependencies"])
+    return names
+
+
+def pnpm_lock_dependencies(path: Path) -> set[str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    return {match.group(1) for match in re.finditer(r"^\s{4,}/?(@[^/\s]+/[^/\s]+|[A-Za-z0-9_.-]+)@[^:]+:", text, re.M)}
+
+
+def audit(project: Path) -> dict:
+    errors = []
+    try:
+        declared = package_dependencies(project)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        return {"passed": False, "errors": [f"package.json: {error}"]}
+    npm = project / "package-lock.json"
+    pnpm = project / "pnpm-lock.yaml"
+    npm_names = npm_lock_dependencies(npm) if npm.exists() else set()
+    pnpm_names = pnpm_lock_dependencies(pnpm) if pnpm.exists() else set()
+    if not npm.exists(): errors.append("package-lock.json is required by npm ci")
+    missing = sorted(declared - npm_names) if npm.exists() else sorted(declared)
+    if missing: errors.append("package-lock missing declared dependencies: " + ", ".join(missing))
+    return {"schemaVersion": "maggie-dependency-lock-audit.v1", "passed": not errors,
+            "errors": errors, "declared": sorted(declared), "npmLock": sorted(npm_names),
+            "pnpmLock": sorted(pnpm_names), "lockfiles": {"npm": npm.exists(), "pnpm": pnpm.exists()}}

package/bundled-tools/runtime/integration_state.py

@@ -0,0 +1,17 @@
+"""Explicit state model for optional Search/AI visibility integrations."""
+
+from __future__ import annotations
+
+
+def integration_state(*, configured: bool, consent_required: bool = False, consent: bool = False, authorized: bool = False, error: str | None = None) -> dict:
+    if error:
+        status = "error"
+    elif not configured:
+        status = "not-configured"
+    elif consent_required and not consent:
+        status = "awaiting-consent"
+    elif not authorized:
+        status = "awaiting-authorization"
+    else:
+        status = "ready"
+    return {"status": status, "configured": configured, "consentRequired": consent_required, "consent": consent, "authorized": authorized, "reason": error or status}