@topy-ai/maggie 0.7.3 → 0.7.5

package/bundled-tools/runtime/maggie_dash_ui.py

@@ -15,6 +15,23 @@ def _component_source(name: str, source: str) -> str:
     return match.group(0) if match else ""
 
 
+def _render_body(component_source: str) -> str:
+    """Return the component implementation, excluding its props signature.
+
+    A declaration and its TypeScript type are evidence that a prop exists, not
+    evidence that the rendered UI uses it. Counting only the implementation
+    prevents a dead prop from passing because it appears twice in the signature.
+    """
+    # Typed destructured parameters contain their own `{...}` block. The
+    # function body is the last opening brace before the first return.
+    return_position = component_source.find("return")
+    opening = component_source.rfind("{", 0, return_position if return_position != -1 else len(component_source))
+    if opening == -1:
+        arrow = component_source.find("=>")
+        opening = component_source.find("{", arrow) if arrow != -1 else -1
+    return component_source[opening + 1:] if opening != -1 else ""
+
+
 def validate(contract: object, sources: Iterable[str] = ()) -> dict:
     errors: list[str] = []
     if not isinstance(contract, dict):
@@ -44,12 +61,29 @@ def validate(contract: object, sources: Iterable[str] = ()) -> dict:
         forbidden = [str(prop) for prop in component.get("forbiddenProps", [])]
         if component_source:
             signature = component_source.split("=>", 1)[0] if "=>" in component_source else component_source[:500]
+            body = _render_body(component_source)
             for prop in props:
-                if len(re.findall(rf"\b{re.escape(prop)}\b", component_source)) < 2:
+                if len(re.findall(rf"\b{re.escape(prop)}\b", body)) < 1:
                     errors.append(f"{name}.{prop} is declared but not evidenced in rendered output")
             for prop in forbidden:
                 if re.search(rf"\b{re.escape(prop)}\b", signature):
                     errors.append(f"{name} declares forbidden dead prop: {prop}")
+    dialogs = contract.get("dialogs")
+    if isinstance(dialogs, dict) and source:
+        for pattern in dialogs.get("forbiddenSourcePatterns", []):
+            pattern = str(pattern)
+            if pattern in source:
+                errors.append(f"dialog contract forbids source pattern: {pattern}")
+        required = [str(item) for item in dialogs.get("requiredLiterals", [])]
+        for key in ("primitive", "overlayPrimitive"):
+            name = str(dialogs.get(key) or "")
+            component_source = _component_source(name, source) if name else ""
+            if not component_source:
+                errors.append(f"dialog source is missing: {name}")
+                continue
+            for literal in required:
+                if literal not in component_source:
+                    errors.append(f"{name} is missing dialog requirement: {literal}")
     return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "components": [item.get("name") for item in components if isinstance(item, dict)]}
 
 

package/bundled-tools/runtime/maggie_sections.py

@@ -0,0 +1,143 @@
+"""Provider-neutral section registry, copy limits, and stable section keys."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import re
+import uuid
+from typing import Any, Iterable
+
+
+SCHEMA = "maggiedash-section-registry.v1"
+IDENTITY_SCHEMA = "maggiedash-section-identity.v1"
+
+
+def validate_registry(value: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["registry must be an object"]}
+    if value.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    sections = value.get("sections")
+    if not isinstance(sections, list) or not sections:
+        errors.append("sections must be a non-empty list")
+        sections = []
+    seen: set[str] = set()
+    for index, section in enumerate(sections):
+        at = f"sections[{index}]"
+        if not isinstance(section, dict):
+            errors.append(f"{at} must be an object")
+            continue
+        section_type = str(section.get("type") or "")
+        if not re.fullmatch(r"[a-z][a-z0-9-]*", section_type):
+            errors.append(f"{at}.type must be a kebab-case identifier")
+        if section_type in seen:
+            errors.append(f"duplicate section type: {section_type}")
+        seen.add(section_type)
+        for field in ("purpose", "usage", "position", "repeatable"):
+            if field not in section:
+                errors.append(f"{at}.{field} is required")
+        if section.get("position") not in {"opening", "body", "closing"}:
+            errors.append(f"{at}.position must be opening, body, or closing")
+        if not isinstance(section.get("repeatable"), bool):
+            errors.append(f"{at}.repeatable must be boolean")
+        fields = section.get("fields")
+        if not isinstance(fields, list) or not fields:
+            errors.append(f"{at}.fields must be a non-empty list")
+            continue
+        field_names: set[str] = set()
+        for field_index, field in enumerate(fields):
+            field_at = f"{at}.fields[{field_index}]"
+            if not isinstance(field, dict) or not field.get("name"):
+                errors.append(f"{field_at} needs a name")
+                continue
+            name = str(field["name"])
+            if name in field_names:
+                errors.append(f"duplicate field: {section_type}.{name}")
+            field_names.add(name)
+            if not isinstance(field.get("limit"), int) or field["limit"] < 0:
+                errors.append(f"{field_at}.limit must be a non-negative integer")
+            if not str(field.get("usage") or "").strip():
+                errors.append(f"{field_at}.usage is required")
+            repeats = field.get("repeats")
+            if repeats is not None and (not isinstance(repeats, dict) or not isinstance(repeats.get("min"), int) or not isinstance(repeats.get("max"), int) or repeats["min"] < 0 or repeats["min"] > repeats["max"]):
+                errors.append(f"{field_at}.repeats must declare valid min/max")
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "sectionTypes": sorted(seen)}
+
+
+def catalogue(registry: dict[str, Any]) -> str:
+    """Render a compact prompt catalogue without duplicating field guidance."""
+    lines: list[str] = []
+    for section in registry.get("sections", []):
+        lines.append(f"{section['type']} — {section['purpose']} | when: {section['usage']} | place: {section['position']} | {'repeatable' if section['repeatable'] else 'once'}")
+        for field in section.get("fields", []):
+            repeat = field.get("repeats")
+            suffix = f" [{repeat['min']}-{repeat['max']} entries]" if isinstance(repeat, dict) else ""
+            lines.append(f"  - {field['name']} ≤{field['limit']} chars{suffix}: {field['usage']}")
+    return "\n".join(lines)
+
+
+def copy_notes(registry: dict[str, Any], sections: object) -> dict[str, Any]:
+    """Return advisory copy/shape notes; over-limit copy is not rejected."""
+    errors: list[str] = []
+    notes: list[dict[str, Any]] = []
+    if not isinstance(sections, list):
+        return {"passed": False, "errors": ["sections must be a list"], "notes": []}
+    specs = {str(item.get("type")): item for item in registry.get("sections", []) if isinstance(item, dict)}
+    for index, section in enumerate(sections):
+        if not isinstance(section, dict):
+            errors.append(f"sections[{index}] must be an object")
+            continue
+        section_type = str(section.get("type") or "")
+        spec = specs.get(section_type)
+        if not spec:
+            errors.append(f"unknown section type: {section_type}")
+            continue
+        for field in spec.get("fields", []):
+            name = str(field.get("name"))
+            value = section.get(name)
+            limit = int(field.get("limit", 0))
+            if isinstance(value, str) and limit and len(value) > limit:
+                notes.append({"at": f"sections[{index}].{name}", "message": f"{len(value)} characters; layout limit is about {limit}"})
+            repeats = field.get("repeats")
+            if isinstance(repeats, dict) and isinstance(value, list) and not repeats["min"] <= len(value) <= repeats["max"]:
+                notes.append({"at": f"sections[{index}].{name}", "message": f"{len(value)} entries; layout expects {repeats['min']}-{repeats['max']}"})
+    return {"passed": not errors, "errors": errors, "notes": notes}
+
+
+def new_section_id(existing: Iterable[str] = ()) -> str:
+    taken = set(existing)
+    while True:
+        candidate = uuid.uuid4().hex[:8]
+        if candidate not in taken:
+            return candidate
+
+
+def ensure_section_ids(sections: list[dict[str, Any]], existing: Iterable[str] = ()) -> list[dict[str, Any]]:
+    result = copy.deepcopy(sections)
+    existing_ids = set(existing)
+    taken = set(existing_ids)
+    for section in result:
+        current = str(section.get("id") or "")
+        if not current or current in existing_ids or current in taken:
+            section["id"] = new_section_id(taken)
+        taken.add(str(section["id"]))
+    return result
+
+
+def section_key(section: object, index: int) -> str:
+    if isinstance(section, dict) and isinstance(section.get("id"), str) and section["id"]:
+        return section["id"]
+    return str(index)
+
+
+def translation_key(page_id: str, section: object, index: int, field: str) -> str:
+    return f"page.{page_id}.sections.{section_key(section, index)}.{field}"
+
+
+def section_id_migration(page_id: str, sections: list[dict[str, Any]]) -> dict[str, Any]:
+    identified = ensure_section_ids(sections)
+    mappings = [{"from": f"page.{page_id}.sections.{index}.", "to": f"page.{page_id}.sections.{section['id']}."} for index, section in enumerate(identified)]
+    return {"schemaVersion": IDENTITY_SCHEMA, "pageId": page_id, "sections": identified, "renameOrder": sorted(mappings, key=lambda item: len(item["from"]), reverse=True), "sourceChecksum": hashlib.sha256(json.dumps(sections, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode()).hexdigest()}

package/bundled-tools/runtime/restart_gate.py

@@ -0,0 +1,22 @@
+"""Evidence gate for writes performed outside the running application."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def validate(value: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": "maggie-restart-gate.v1", "passed": False, "errors": ["restart gate must be an object"]}
+    if value.get("schemaVersion") != "maggie-restart-gate.v1":
+        errors.append("unsupported restart gate schema")
+    if value.get("outOfBandWrite") is not True:
+        errors.append("outOfBandWrite must be true for this gate")
+    if value.get("restartRequired") is not True:
+        errors.append("restartRequired must be true after an out-of-band write")
+    if not str(value.get("restartCommand") or "").strip():
+        errors.append("restartCommand is required")
+    if value.get("verificationAfterRestart") is not True:
+        errors.append("verificationAfterRestart must be true")
+    return {"schemaVersion": "maggie-restart-gate.v1", "passed": not errors, "errors": errors, "order": ["write", "restart", "verify"]}

package/bundled-tools/runtime/surface_coverage.py

@@ -0,0 +1,48 @@
+"""Coverage checks that follow the surface and locale changed by a release."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+SCHEMA = "maggie-surface-coverage.v1"
+
+
+def validate_contract(contract: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(contract, dict):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["coverage contract must be an object"]}
+    if contract.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    surfaces = contract.get("surfaces")
+    if not isinstance(surfaces, list) or not surfaces:
+        errors.append("surfaces must be a non-empty list")
+        surfaces = []
+    seen: set[tuple[str, str]] = set()
+    for index, item in enumerate(surfaces):
+        if not isinstance(item, dict) or not item.get("name") or not isinstance(item.get("routes"), list) or not item["routes"] or not isinstance(item.get("locales"), list) or not item["locales"]:
+            errors.append(f"surfaces[{index}] needs name, routes, and locales")
+            continue
+        for locale in item["locales"]:
+            key = (str(item["name"]), str(locale))
+            if key in seen:
+                errors.append(f"duplicate surface/locale: {key[0]}/{key[1]}")
+            seen.add(key)
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale in seen)}
+
+
+def compare(contract: dict[str, Any], observations: object) -> dict[str, Any]:
+    checked = validate_contract(contract)
+    if not checked["passed"]:
+        return {**checked, "observedPairs": [], "missing": [], "failed": []}
+    expected = {(str(item["name"]), str(locale)) for item in contract["surfaces"] for locale in item["locales"]}
+    observed: dict[tuple[str, str], dict[str, Any]] = {}
+    for item in observations if isinstance(observations, list) else []:
+        if not isinstance(item, dict):
+            continue
+        key = (str(item.get("surface") or ""), str(item.get("locale") or ""))
+        if key in expected:
+            observed[key] = item
+    missing = sorted(f"{surface}/{locale}" for surface, locale in expected - observed.keys())
+    failed = sorted(f"{surface}/{locale}" for (surface, locale), item in observed.items() if item.get("passed") is not True or int(item.get("status", 200)) >= 400)
+    return {"schemaVersion": SCHEMA, "passed": not missing and not failed, "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale in expected), "observedPairs": sorted(f"{surface}/{locale}" for surface, locale in observed), "missing": missing, "failed": failed}

package/package.json

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

package/references/maggiedash-telemetry-contract.md

@@ -0,0 +1,12 @@
+# MaggieDash telemetry contract
+
+Every measurement path must call the shared first-party traffic filter before
+incrementing a counter or writing a measurement event. This includes page
+views, 404/not-found rows, redirect hits, booking clicks, analytics events and
+operational audit counters. Filtering only page views leaves synthetic sweeps
+in the other totals.
+
+Use `should_record_measurement(event)` from
+`tools/runtime/analytics_traffic.py`. The filter accepts explicit Maggie/test
+markers and known toolchain user agents; it never guesses identity from IP
+addresses or private user fields.