@topy-ai/maggie 0.7.17 → 0.7.19

package/bundled-tools/clis/maggie_docs.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Audit project documentation for stale trackers and unreferenced files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+from pathlib import Path
+
+
+DOCUMENT_EXTENSIONS = {".md", ".mdx", ".json", ".yaml", ".yml"}
+SKIP_PARTS = {".git", "node_modules", "dist", "build", ".next"}
+COMPLETED_RE = re.compile(r"(?i)\b(?:done|complete|completed|shipped|resolved|closed)\b")
+TRACKER_RE = re.compile(r"(?i)(?:plan|task|progress|roadmap|todo)")
+RECORD_RE = re.compile(r"(?i)(?:audit|report|evidence|log|feedback|record)")
+
+
+def _files(root: Path) -> list[Path]:
+    return sorted(
+        path for path in root.rglob("*")
+        if path.is_file() and path.suffix.casefold() in DOCUMENT_EXTENSIONS
+        and not any(part in SKIP_PARTS for part in path.relative_to(root).parts)
+    )
+
+
+def _category(path: Path) -> str:
+    if path.suffix.casefold() in {".json", ".yaml", ".yml"}:
+        return "data"
+    name = path.stem
+    if TRACKER_RE.search(name):
+        return "plan"
+    if RECORD_RE.search(name):
+        return "record"
+    return "reference"
+
+
+def _identity(path: Path, text: str) -> str:
+    heading = next((line.strip().lstrip("#").strip() for line in text.splitlines() if line.lstrip().startswith("#")), "")
+    value = heading or path.stem
+    return re.sub(r"[^a-z0-9]+", "-", value.casefold()).strip("-")
+
+
+def _last_change(project: Path, relative: str) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(project), "log", "-1", "--format=%cI", "--", relative],
+            capture_output=True, text=True, check=False,
+        )
+    except OSError:
+        return None
+    value = result.stdout.strip()
+    return value or None
+
+
+def audit(project: Path, docs_dir: str = "docs") -> dict:
+    root = project.resolve()
+    docs = (root / docs_dir).resolve()
+    if not docs.is_dir():
+        return {"schemaVersion": "maggie-docs-audit.v1", "passed": False, "errors": [f"docs directory does not exist: {docs}"], "files": []}
+    files = _files(docs)
+    corpus: list[tuple[Path, str]] = []
+    for path in _files(root):
+        try:
+            corpus.append((path, path.read_text(encoding="utf-8", errors="replace")))
+        except OSError:
+            continue
+    entries = []
+    for path in files:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError as error:
+            entries.append({"path": str(path.relative_to(root)), "status": "unreadable", "error": str(error)})
+            continue
+        relative = str(path.relative_to(root))
+        basename = path.name
+        inbound = sum(1 for source, source_text in corpus if source != path and (relative in source_text or basename in source_text))
+        category = _category(path)
+        completed_tracker = category == "plan" and bool(COMPLETED_RE.search(text))
+        findings: list[str] = []
+        if completed_tracker:
+            findings.append("completed-progress-tracker")
+        if inbound == 0 and category in {"reference", "data"}:
+            findings.append("unreferenced")
+        entries.append({
+            "path": relative,
+            "category": category,
+            "inboundReferences": inbound,
+            "lastChanged": _last_change(root, relative),
+            "completedTracker": completed_tracker,
+            "openTracker": category == "plan" and not completed_tracker,
+            "identity": _identity(path, text),
+            "findings": findings,
+        })
+    identities: dict[str, list[dict]] = {}
+    for item in entries:
+        identities.setdefault(item.get("identity", ""), []).append(item)
+    duplicate_groups = [group for key, group in identities.items() if key and len(group) > 1]
+    duplicate_paths = {item["path"] for group in duplicate_groups for item in group}
+    for item in entries:
+        item.pop("identity", None)
+        if item["path"] in duplicate_paths:
+            item["findings"].append("duplicate-candidate")
+        item["staleCandidate"] = bool(item["findings"])
+    findings = [item for item in entries if item.get("findings")]
+    return {
+        "schemaVersion": "maggie-docs-audit.v1",
+        "passed": True,
+        "project": str(root),
+        "docsDirectory": str(docs.relative_to(root)),
+        "fileCount": len(entries),
+        "findingCount": len(findings),
+        "summary": {
+            "reference": sum(item.get("category") == "reference" for item in entries),
+            "record": sum(item.get("category") == "record" for item in entries),
+            "plan": sum(item.get("category") == "plan" for item in entries),
+            "data": sum(item.get("category") == "data" for item in entries),
+            "completedTrackers": sum(item.get("completedTracker", False) for item in entries),
+            "openTrackers": sum(item.get("openTracker", False) for item in entries),
+            "unreferenced": sum("unreferenced" in item.get("findings", []) for item in entries),
+            "duplicateCandidates": len(duplicate_groups),
+            "staleCandidates": sum(item.get("staleCandidate", False) for item in entries),
+        },
+        "files": entries,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("audit", nargs="?", choices=("audit",), default="audit")
+    parser.add_argument("--project", default=".")
+    parser.add_argument("--docs-dir", default="docs")
+    parser.add_argument("--fail-on-findings", action="store_true")
+    parser.add_argument("--output")
+    args = parser.parse_args()
+    result = audit(Path(args.project), args.docs_dir)
+    if args.fail_on_findings and result.get("findingCount"):
+        result["passed"] = False
+        result.setdefault("errors", []).append("documentation findings require review")
+    if args.output:
+        output = Path(args.output).expanduser().resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        result["output"] = str(output)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result.get("passed") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_feedback.py

@@ -20,6 +20,12 @@ from urllib.request import Request, urlopen
 
 DEFAULT_ENDPOINT = "https://feedback.noblox.app/api/feedback"
 SECRET_RE = re.compile(r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|npm_config[^=]*|authorization)\s*[=:]\s*)[^\s,;]+")
+LOCAL_PATH_RE = re.compile(
+    r"(?<![A-Za-z0-9])(?:~/(?:[^\s,;:)\]}]+/)*[^\s,;:)\]}]+|"
+    r"/(?:home|Users|private|tmp|var|mnt|opt|root|srv|workspace|workspaces)(?:/[^\s,;:)\]}]+)+|"
+    r"[A-Za-z]:[\\/]+(?:[^\\/\s,;:)\]}]+[\\/]+)*[^\\/\s,;:)\]}]+|"
+    r"\\\\[^\\/\s,;:)\]}]+(?:[\\/]+[^\\/\s,;:)\]}]+)+)"
+)
 VERSION_RE = re.compile(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?")
 ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
 REPO_ROOT = Path(__file__).resolve().parents[2]
@@ -30,7 +36,8 @@ def now() -> str:
 
 
 def safe_text(value: object) -> str:
-    return SECRET_RE.sub(r"\1[REDACTED]", str(value or "")).strip()
+    value = SECRET_RE.sub(r"\1[REDACTED]", str(value or ""))
+    return LOCAL_PATH_RE.sub("[LOCAL_PATH_REDACTED]", value).strip()
 
 
 def project_fingerprint(project: Path) -> str:
@@ -90,6 +97,11 @@ def collect(args: argparse.Namespace) -> int:
     skill = args.skill or report.get("skill") or report.get("workflow") or "unknown"
     run_id = args.run_id or report.get("runId") or report.get("jobId") or ""
     actual = args.actual or report.get("actual") or report.get("error") or report.get("message") or ""
+    fixed = bool(args.fixed or report.get("fixed") is True or report.get("status") == "fixed")
+    resolution = safe_text(args.resolution or report.get("resolution"))
+    validation = safe_text(args.validation or report.get("validation"))
+    if fixed and (not resolution or not validation):
+        raise ValueError("fixed feedback requires non-empty --resolution and --validation")
     context = {"projectFingerprint": project_fingerprint(project)}
     if args.allow_project_context and args.context_note:
         context["note"] = safe_text(args.context_note)
@@ -103,15 +115,15 @@ def collect(args: argparse.Namespace) -> int:
         "skill": skill,
         "runId": run_id,
         "phase": args.phase or report.get("phase") or "",
-        "status": report.get("status") or ("fixed" if args.fixed else "reported"),
+        "status": report.get("status") or ("fixed" if fixed else "reported"),
         "summary": safe_text(args.summary),
         "expected": safe_text(args.expected),
         "actual": safe_text(actual),
         "errorFingerprint": safe_text(args.error_fingerprint or report.get("errorFingerprint") or ""),
         "stepsToReproduce": [safe_text(step) for step in args.reproduce],
-        "fixed": bool(args.fixed),
-        "resolution": safe_text(args.resolution),
-        "validation": safe_text(args.validation),
+        "fixed": fixed,
+        "resolution": resolution,
+        "validation": validation,
         "attachments": [attachment(value) for value in args.screenshot],
         "environment": {"os": platform.system().lower(), "python": platform.python_version()},
         "privacy": {"secretsRedacted": True, "projectContextAllowed": bool(args.allow_project_context)},

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -224,6 +224,8 @@ def record(args: argparse.Namespace) -> int:
         raise ValueError("a failed scenario must have a recorded fix before retest")
     if phase == "test" and args.status == "fail" and not (args.expected and args.actual and args.error_fingerprint):
         raise ValueError("a failed test requires --expected, --actual and --error-fingerprint")
+    if phase in {"test", "retest"} and args.status == "pass" and not args.evidence:
+        raise ValueError("a passing test requires --evidence from the browser adapter")
     event = {
         "at": now(),
         "phase": phase,

package/bundled-tools/clis/maggie_release.py

@@ -16,7 +16,7 @@ from urllib.error import HTTPError, URLError
 from urllib.request import Request, urlopen
 from datetime import datetime, timezone
 from pathlib import Path
-from urllib.parse import urljoin
+from urllib.parse import urljoin, urlsplit
 
 
 ROOT = Path(__file__).resolve().parent
@@ -130,14 +130,23 @@ def evidence_gate(project: Path, environment: str) -> dict:
 def changed_surface_gate(project: Path) -> dict:
     """Require visual/runtime evidence when a visitor-facing surface changed."""
     try:
-        changed = subprocess.run(
+        changed_output = subprocess.run(
             ["git", "-C", str(project), "diff", "--name-only"],
             capture_output=True, text=True, check=True,
         ).stdout.splitlines()
+        staged_output = subprocess.run(
+            ["git", "-C", str(project), "diff", "--cached", "--name-only"],
+            capture_output=True, text=True, check=True,
+        ).stdout.splitlines()
+        untracked_output = subprocess.run(
+            ["git", "-C", str(project), "ls-files", "--others", "--exclude-standard", "-z"],
+            capture_output=True, text=True, check=True,
+        ).stdout.split("\0")
     except (OSError, subprocess.CalledProcessError):
         return {"name": "changed-surface-evidence", "passed": True, "exitCode": 0,
                 "result": {"passed": True, "changed": False, "reason": "project is not a git worktree"}, "stderr": ""}
     visitor_suffixes = {".astro", ".css", ".scss", ".html", ".jsx", ".tsx", ".js", ".ts", ".svg", ".png", ".jpg", ".jpeg", ".webp"}
+    changed = set(changed_output) | set(staged_output) | {path for path in untracked_output if path}
     surfaces = sorted(path for path in changed if Path(path).suffix.lower() in visitor_suffixes)
     if not surfaces:
         return {"name": "changed-surface-evidence", "passed": True, "exitCode": 0,
@@ -181,6 +190,82 @@ def changed_surface_gate(project: Path) -> dict:
             "result": {"passed": not errors, "changed": True, "surfaces": surfaces, "evidence": evidence, "errors": errors}, "stderr": ""}
 
 
+def _origin(value: object) -> str:
+    try:
+        parsed = urlsplit(str(value or ""))
+        if parsed.scheme and parsed.netloc:
+            return f"{parsed.scheme.lower()}://{parsed.netloc.lower()}"
+    except ValueError:
+        pass
+    return ""
+
+
+def _qa_run_matches(run: dict, manifest_label: str | None, environment: str, base_url: str | None) -> bool:
+    if run.get("schemaVersion") != "maggie.qa-run.v1":
+        return False
+    if run.get("environment") != environment:
+        return False
+    if manifest_label and run.get("scenarioManifest") != manifest_label:
+        return False
+    if base_url and _origin(run.get("baseUrl")) != _origin(base_url):
+        return False
+    return isinstance(run.get("scenarios"), dict) and bool(run.get("scenarios"))
+
+
+def qa_gate(project: Path, environment: str, base_url: str | None = None) -> dict:
+    """Consume the latest matching project QA run without running a browser."""
+    manifest = project / ".maggie" / "scenario-manifest.json"
+    run_dir = project / ".maggie" / "qa-runs"
+    run_paths = sorted(run_dir.glob("*.json")) if run_dir.is_dir() else []
+    configured = manifest.is_file() or bool(run_paths)
+    if not configured:
+        return {"name": "scenario-qa", "passed": True, "exitCode": 0,
+                "result": {"passed": True, "state": "not-configured", "configured": False,
+                            "reason": "no scenario manifest or QA run directory"}, "stderr": ""}
+
+    try:
+        manifest_label = str(manifest.relative_to(project)) if manifest.is_file() else None
+    except ValueError:
+        manifest_label = manifest.name if manifest.is_file() else None
+    candidates: list[tuple[Path, dict]] = []
+    invalid_count = 0
+    for path in run_paths:
+        try:
+            value = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(value, dict) and _qa_run_matches(value, manifest_label, environment, base_url):
+                candidates.append((path, value))
+        except (OSError, json.JSONDecodeError):
+            invalid_count += 1
+    if not candidates:
+        return {"name": "scenario-qa", "passed": False, "exitCode": 1,
+                "result": {"passed": False, "state": "inconclusive", "configured": True,
+                            "errors": ["no matching scenario QA run", f"invalidRuns={invalid_count}"]}, "stderr": ""}
+
+    path, run = max(candidates, key=lambda item: str(item[1].get("updatedAt") or item[1].get("createdAt") or ""))
+    errors: list[str] = []
+    summary = run.get("summary") if isinstance(run.get("summary"), dict) else {}
+    if summary.get("gate") != "pass":
+        errors.append("latest matching QA run is not passed")
+    for scenario in run.get("scenarios", {}).values():
+        if not isinstance(scenario, dict) or scenario.get("status") != "pass":
+            errors.append("latest matching QA run contains a non-passing scenario")
+            continue
+        history = scenario.get("history") if isinstance(scenario.get("history"), list) else []
+        last = history[-1] if history else {}
+        if last.get("phase") not in {"test", "retest"} or last.get("status") != "pass":
+            errors.append("latest matching QA run has a scenario without a passing final test")
+        if not isinstance(last.get("evidence"), list) or not last.get("evidence"):
+            errors.append("latest matching QA run has a scenario without browser evidence")
+    passed = not errors
+    try:
+        report_path = str(path.relative_to(project))
+    except ValueError:
+        report_path = path.name
+    return {"name": "scenario-qa", "passed": passed, "exitCode": 0 if passed else 1,
+            "result": {"passed": passed, "state": "passed" if passed else "failed", "configured": True,
+                        "run": report_path, "updatedAt": run.get("updatedAt"), "errors": errors}, "stderr": ""}
+
+
 def editorial_gate(project: Path) -> dict:
     """Require explicit editorial approval for every launch category.
 
@@ -279,6 +364,7 @@ def main() -> int:
 
     gates = []
     gates.append(changed_surface_gate(project))
+    gates.append(qa_gate(project, args.environment, args.base_url))
     gates.append(build_gate(project))
     for name, command in build_gates(project, args.environment, args.target, not args.skip_compatibility):
         gates.append(run_gate(name, command, project))

package/bundled-tools/clis/maggie_service_booking.py

@@ -12,6 +12,7 @@ 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
+from booking_capabilities import audit_matrix  # noqa: E402
 
 NOW = lambda: datetime.now(timezone.utc).isoformat()
 MONEY = re.compile(r"(?:£|GBP\s*)\s*([0-9]+(?:[.,][0-9]{1,2})?)", re.I)
@@ -76,7 +77,8 @@ def parse(source, provider):
                 currency=(offer.get("priceCurrency") or ("GBP" if price and ("£" in text or provider=="fresha") else None))
                 if price is None and dm is None: continue
                 amount=int(round(float(str(price).replace(",",""))*100)) if price is not None else None
-                variants.append({"id":f"{slug(name)}:{dm.group(1) if dm else 'default'}","title":offer.get("name") or (f"{dm.group(1)} minutes" if dm else "Standard"),"durationMinutes":int(dm.group(1)) if dm else None,"price":{"amountMinor":amount,"currency":currency,"display":f"£{amount/100:.2f}" if amount is not None and currency=="GBP" else None}})
+                provider_variant_id = offer.get("sku") or offer.get("@id") or offer.get("id")
+                variants.append({"id":str(provider_variant_id or f"{slug(name)}:{dm.group(1) if dm else 'default'}"),"idSource":"provider" if provider_variant_id else "derived","variantSource":"native" if provider_variant_id else "derived-offers","title":offer.get("name") or (f"{dm.group(1)} minutes" if dm else "Standard"),"durationMinutes":int(dm.group(1)) if dm else None,"price":{"amountMinor":amount,"currency":currency,"display":f"£{amount/100:.2f}" if amount is not None and currency=="GBP" else None}})
             url=item.get("url") or item.get("sameAs")
             if not variants and not url: continue
             pid=str(item.get("providerServiceId") or item.get("productID") or item.get("sku") or slug(name))
@@ -113,7 +115,8 @@ def parse_fresha_embedded(raw, source):
                     parsed_amount, parsed_currency=money_value(display or "")
                     caption=variant.get("caption") or ""
                     duration=duration_minutes(caption) or round(float(variant.get("maxInSeconds") or variant.get("minInSeconds") or item.get("maxInSeconds") or item.get("minInSeconds") or 0)/60) or None
-                    variants.append({"id":str(variant.get("id") or f'{item["serviceId"]}:default'),"title":variant.get("name") or caption or "Standard","durationMinutes":duration,"price":{"amountMinor":parsed_amount if parsed_amount is not None else amount,"currency":parsed_currency or currency,"display":display}})
+                    provider_variant_id = variant.get("id")
+                    variants.append({"id":str(provider_variant_id or f'{item["serviceId"]}:default'),"idSource":"provider" if provider_variant_id else "derived","variantSource":"native" if provider_variant_id else "single-fallback","title":variant.get("name") or caption or "Standard","durationMinutes":duration,"price":{"amountMinor":parsed_amount if parsed_amount is not None else amount,"currency":parsed_currency or currency,"display":display}})
                 if not variants: continue
                 booking=item.get("bookingUrl") or f'{source.split("?")[0]}/booking?offerItemId={quote(str(item.get("id") or ""))}'
                 record=make_record("fresha",source,str(item["serviceId"]),str(item["name"]),str(item.get("description") or ""),variants,booking,[])
@@ -157,7 +160,7 @@ def parse_fresha_embedded(raw, source):
         for caption, display, vid, vname in variant_pattern.findall(match.group("variants")):
             duration=duration_minutes(caption)
             amount, currency=money_value(display)
-            variants.append({"id":vid,"title":vname or caption,"durationMinutes":duration,"price":{"amountMinor":amount,"currency":currency,"display":display}})
+            variants.append({"id":vid,"idSource":"provider","variantSource":"native","title":vname or caption,"durationMinutes":duration,"price":{"amountMinor":amount,"currency":currency,"display":display}})
         if not variants: continue
         name=variants[0]["title"]
         records.append(make_record("fresha",source,match.group("pid"),name,description,variants,None,[]))
@@ -436,6 +439,40 @@ def cmd_category_hash(args):
     print(json.dumps(report, indent=2, ensure_ascii=False))
     return 0 if not errors else 1
 
+
+def cmd_capability_audit(args):
+    """Validate provider declarations and emit a fixture-backed capability matrix."""
+    project = root(args)
+    def read(path_value):
+        path_value = Path(path_value)
+        path_value = path_value if path_value.is_absolute() else project / path_value
+        return path_value.resolve(), json.loads(path_value.resolve().read_text(encoding="utf-8"))
+    try:
+        catalogue_path, catalogue = read(args.catalogue)
+        declaration_path, declarations = read(args.capabilities_file)
+        fixture = None
+        fixture_path = None
+        fixture_digest = None
+        if args.fixture:
+            fixture_path, fixture = read(args.fixture)
+            fixture_digest = hashlib.sha256(fixture_path.read_bytes()).hexdigest()
+        result = audit_matrix(declarations, catalogue, provider=args.provider, fixture=fixture,
+                              fixture_name=fixture_path.name if fixture_path else None,
+                              fixture_sha256=fixture_digest)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(json.dumps({"schemaVersion": "maggie-provider-variant-capabilities.v1", "passed": False, "errors": [str(error)]}, indent=2))
+        return 1
+    output = Path(args.output) if args.output else project / "docs" / "provider-variant-capabilities.json"
+    if not output.is_absolute():
+        output = project / output
+    output = output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    result["catalogue"] = catalogue_path.name
+    result["declarations"] = declaration_path.name
+    output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "passed" if result["passed"] else "failed", "report": str(output), "providers": len(result["providers"]), "errors": result["errors"]}, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
 def category_audit_report(project, pages_dir, copy_data, rendered_dir=None, environment="staging"):
     errors = []
     copy_path = (project / copy_data).resolve()
@@ -976,6 +1013,7 @@ def main():
     q=sub.add_parser("category-editorial-review"); q.add_argument("--project",default="."); q.add_argument("--copy-data",default="docs/category-page-copy.json"); q.add_argument("--category",action="append",help="category to review; defaults to all seven launch categories"); q.add_argument("--reviewer"); q.add_argument("--evidence",action="append",default=[],help="review evidence path or URL; repeatable"); q.add_argument("--apply",action="store_true",help="write explicit editorial approval metadata"); q.add_argument("--confirm",action="store_true",help="confirm that the selected records were actually reviewed by a human")
     q=sub.add_parser("category-hash"); q.add_argument("--project",default="."); q.add_argument("--copy-data",required=True); q.add_argument("--apply",action="store_true",help="backfill deterministic provenance hashes in this generated artifact")
     q=sub.add_parser("fact-audit"); q.add_argument("--project",default="."); q.add_argument("--backfill-source",action="store_true",help="copy the catalogue sourceUrl into records that have no sourceUrl"); q.add_argument("--overrides",help="JSON of human-approved, evidenced descriptions for provider gaps"); q.add_argument("--apply-overrides",action="store_true",help="apply only approved fact overrides to the draft catalogue")
+    q=sub.add_parser("capability-audit", help="validate provider variant declarations and fixture evidence"); q.add_argument("--project",default="."); q.add_argument("--provider"); q.add_argument("--catalogue",default=".maggie/booking/services.json"); q.add_argument("--capabilities-file",default=".maggie/booking/provider-capabilities.json"); q.add_argument("--fixture",help="sanitized provider fixture JSON"); q.add_argument("--output")
     q=sub.add_parser("category-context"); q.add_argument("--project",default="."); q.add_argument("--output")
     q=sub.add_parser("validate-copy"); q.add_argument("--project",default="."); q.add_argument("--service-id",required=True); q.add_argument("--copy-data",required=True,help="AI-authored service copy JSON")
     q=sub.add_parser("sitemap-audit"); q.add_argument("--project",default="."); q.add_argument("--index",required=True,help="rendered sitemap index XML"); q.add_argument("--sitemap-dir",required=True,help="directory containing rendered child sitemap XML files"); q.add_argument("--base-url",help="reserved for URL evidence and report context"); q.add_argument("--environment",choices=("development","staging","production"),default="staging")
@@ -997,6 +1035,7 @@ def main():
     if a.command=="category-editorial-review": return cmd_category_editorial_review(a)
     if a.command=="category-hash": return cmd_category_hash(a)
     if a.command=="fact-audit": return cmd_fact_audit(a)
+    if a.command=="capability-audit": return cmd_capability_audit(a)
     if a.command=="category-context": return cmd_category_context(a)
     if a.command=="validate-copy": return cmd_validate_copy(a)
     if a.command=="sitemap-audit": return cmd_sitemap_audit(a)

package/bundled-tools/runtime/booking_capabilities.py

@@ -0,0 +1,137 @@
+"""Provider-neutral service variant capability matrix validation."""
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+SCHEMA_VERSION = "maggie-provider-variant-capabilities.v1"
+VARIANT_MODES = {"native", "derived-offers", "single-fallback", "blocked"}
+PRICE_SEMANTICS = {"minor-unit", "minor-unit-and-display", "display-only", "unavailable", "unknown"}
+STABLE_ID_CONFIDENCE = {"high", "medium", "low", "unknown", "blocked"}
+
+
+def _services(value: object) -> list[dict[str, Any]]:
+    if isinstance(value, dict) and isinstance(value.get("services"), list):
+        return [item for item in value["services"] if isinstance(item, dict)]
+    if isinstance(value, list):
+        return [item for item in value if isinstance(item, dict)]
+    return []
+
+
+def _fixture_evidence(fixture: object | None, name: str | None, digest: str | None) -> dict[str, Any]:
+    services = _services(fixture)
+    variants = [variant for service in services for variant in _services({"services": service.get("variants", [])})]
+    return {
+        "provided": fixture is not None,
+        "name": name or None,
+        "sha256": digest or None,
+        "serviceCount": len(services),
+        "variantCounts": [len(service.get("variants") or []) for service in services],
+        "allVariantIdsPresent": bool(variants) and all(str(item.get("id") or "").strip() for item in variants),
+        "allVariantSourcesPresent": bool(variants) and all(str(item.get("variantSource") or "").strip() for item in variants),
+    }
+
+
+def audit_provider(declaration: object, catalogue: object, *, fixture: object | None = None,
+                   fixture_name: str | None = None, fixture_sha256: str | None = None) -> dict[str, Any]:
+    """Validate one provider declaration against catalogue and fixture evidence."""
+    item = declaration if isinstance(declaration, dict) else {}
+    provider = str(item.get("provider") or "").strip()
+    mode = str(item.get("variantMode") or "").strip()
+    price_semantics = str(item.get("priceSemantics") or "").strip()
+    stable_id_confidence = str(item.get("stableIdConfidence") or "").strip()
+    errors: list[str] = []
+    if not provider:
+        errors.append("provider is required")
+    if mode not in VARIANT_MODES:
+        errors.append("variantMode must be native, derived-offers, single-fallback, or blocked")
+    if price_semantics not in PRICE_SEMANTICS:
+        errors.append("priceSemantics is unsupported")
+    if stable_id_confidence not in STABLE_ID_CONFIDENCE:
+        errors.append("stableIdConfidence is unsupported")
+
+    services = _services(catalogue)
+    active_services = [service for service in services if service.get("status", "active") != "archived"]
+    variants = [variant for service in active_services for variant in (service.get("variants") or []) if isinstance(variant, dict)]
+    observed_modes = Counter(str(variant.get("variantSource") or "unknown") for variant in variants)
+    all_ids = bool(variants) and all(str(variant.get("id") or "").strip() for variant in variants)
+    native_id_sources = all(str(variant.get("idSource") or "") in {"provider", "native"} for variant in variants) if variants else False
+    structured_prices = bool(variants) and all(
+        isinstance(variant.get("price"), dict)
+        and isinstance(variant["price"].get("amountMinor"), int)
+        and str(variant["price"].get("currency") or "").isalpha()
+        for variant in variants
+    )
+    if not services:
+        errors.append("catalogue has no services")
+    if mode != "blocked" and not variants:
+        errors.append("declared non-blocked provider has no active variants")
+    if mode == "native" and variants and not native_id_sources:
+        errors.append("native variants require provider/native idSource evidence")
+    if mode == "single-fallback" and any(len(service.get("variants") or []) > 1 for service in active_services):
+        errors.append("single-fallback provider has a service with multiple variants")
+    expected_source = {"native": "native", "derived-offers": "derived-offers", "single-fallback": "single-fallback"}.get(mode)
+    if expected_source and variants and any(source != expected_source for source in observed_modes):
+        errors.append(f"catalogue variantSource does not match declared {mode} mode")
+    if stable_id_confidence == "high" and not native_id_sources:
+        errors.append("high stable-ID confidence requires provider/native idSource evidence")
+    if fixture is None:
+        errors.append("fixture evidence is required")
+
+    evidence = _fixture_evidence(fixture, fixture_name, fixture_sha256)
+    if fixture is not None and evidence["serviceCount"] == 0:
+        errors.append("fixture evidence has no services")
+    if mode != "blocked" and fixture is not None and not evidence["allVariantIdsPresent"]:
+        errors.append("fixture evidence is missing variant IDs")
+    if mode != "blocked" and fixture is not None and not evidence["allVariantSourcesPresent"]:
+        errors.append("fixture evidence is missing variant sources")
+    if price_semantics in {"minor-unit", "minor-unit-and-display"} and variants and not structured_prices:
+        errors.append("declared minor-unit price semantics require amountMinor and currency")
+    if price_semantics == "display-only" and variants and any(
+        isinstance(variant.get("price"), dict) and variant["price"].get("amountMinor") is not None
+        for variant in variants
+    ):
+        errors.append("display-only price semantics cannot contain amountMinor")
+    if price_semantics == "unavailable" and variants and any(variant.get("price") for variant in variants):
+        errors.append("unavailable price semantics cannot contain price data")
+    if provider and isinstance(catalogue, dict) and catalogue.get("provider") and catalogue.get("provider") != provider:
+        errors.append("catalogue provider does not match declaration")
+
+    passed = not errors
+    return {
+        "provider": provider or None,
+        "variantMode": mode or None,
+        "priceSemantics": price_semantics or None,
+        "stableIdConfidence": stable_id_confidence or None,
+        "observed": {
+            "serviceCount": len(services),
+            "activeServiceCount": len(active_services),
+            "variantCount": len(variants),
+            "variantSources": dict(sorted(observed_modes.items())),
+            "allVariantIdsPresent": all_ids,
+            "allStructuredPrices": structured_prices,
+        },
+        "fixtureEvidence": evidence,
+        "passed": passed,
+        "errors": errors,
+    }
+
+
+def audit_matrix(declarations: object, catalogue: object, *, provider: str | None = None,
+                 fixture: object | None = None, fixture_name: str | None = None,
+                 fixture_sha256: str | None = None) -> dict[str, Any]:
+    """Validate a machine-readable provider declaration file."""
+    if isinstance(declarations, dict) and declarations.get("providers"):
+        entries = declarations["providers"]
+    elif isinstance(declarations, list):
+        entries = declarations
+    else:
+        entries = []
+    if not isinstance(entries, list):
+        entries = []
+    selected = [entry for entry in entries if isinstance(entry, dict) and (not provider or entry.get("provider") == provider)]
+    if not selected:
+        return {"schemaVersion": SCHEMA_VERSION, "passed": False, "providers": [], "errors": ["no provider declaration selected"]}
+    results = [audit_provider(entry, catalogue, fixture=fixture, fixture_name=fixture_name, fixture_sha256=fixture_sha256) for entry in selected]
+    return {"schemaVersion": SCHEMA_VERSION, "passed": all(result["passed"] for result in results), "providers": results,
+            "errors": [f"{result.get('provider') or 'unknown'}: {error}" for result in results for error in result["errors"]]}

package/bundled-tools/runtime/maggie_api_contract.py

@@ -4,11 +4,17 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+from pathlib import Path
+import json
 
 
 SCHEMA = "maggie-api-contract.v1"
 METHODS = {"get", "post", "put", "patch", "delete", "head", "options", "trace"}
 BODY_METHODS = {"post", "put", "patch"}
+MAX_SPEC_BYTES = 2_000_000
 
 
 def _has_schema(value: object) -> bool:
@@ -95,3 +101,48 @@ def validate_api_contract(spec: object) -> dict[str, Any]:
             operations.append(record)
     return {"schemaVersion": SCHEMA, "passed": not errors, "operations": operations, "errors": errors,
             "operationCount": len(operations), "errorCount": len(errors)}
+
+
+def _safe_url(source: str) -> tuple[str, str]:
+    parsed = urlparse(source)
+    if parsed.scheme not in {"https", "http"} or not parsed.netloc:
+        raise ValueError("API contract source must be a local file or an absolute HTTPS URL")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("API contract URL must not contain credentials, query parameters, or fragments")
+    host = (parsed.hostname or "").casefold()
+    if parsed.scheme == "http" and host not in {"localhost", "127.0.0.1", "::1"}:
+        raise ValueError("plain HTTP is allowed only for loopback development sources")
+    display = f"{parsed.scheme}://{parsed.netloc}{parsed.path or '/'}"
+    return source, display
+
+
+def load_api_contract_source(source: str | Path, *, timeout: float = 20.0) -> tuple[object, dict[str, Any]]:
+    """Load a local JSON spec or fetch a safe URL without writing the response.
+
+    The caller receives source metadata suitable for an audit report. Response
+    bodies are parsed in memory only, so a live contract check cannot silently
+    create a project artifact containing a private API document.
+    """
+    value = str(source)
+    parsed = urlparse(value)
+    if parsed.scheme in {"https", "http"}:
+        requested, display = _safe_url(value)
+        request = Request(requested, headers={"Accept": "application/json", "User-Agent": "MaggieApiContract/1"})
+        try:
+            with urlopen(request, timeout=timeout) as response:
+                raw = response.read(MAX_SPEC_BYTES + 1)
+        except (HTTPError, URLError, TimeoutError) as error:
+            raise RuntimeError(f"could not fetch API contract URL: {error}") from error
+        if len(raw) > MAX_SPEC_BYTES:
+            raise ValueError(f"API contract response exceeds {MAX_SPEC_BYTES} bytes")
+        try:
+            document = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ValueError("API contract URL did not return a UTF-8 JSON document") from error
+        return document, {"sourceType": "url", "source": display}
+
+    path = Path(value).expanduser().resolve()
+    raw = path.read_bytes()
+    if len(raw) > MAX_SPEC_BYTES:
+        raise ValueError(f"API contract file exceeds {MAX_SPEC_BYTES} bytes")
+    return json.loads(raw.decode("utf-8")), {"sourceType": "file", "source": str(path)}