@topy-ai/maggie 0.6.9 → 0.7.0

package/bundled-tools/runtime/service_variants.py

@@ -0,0 +1,152 @@
+"""Provider-neutral service variant lifecycle and URL/layout contract."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+VARIANT_TYPES = {"location", "event", "holiday"}
+STATUSES = ("draft", "review", "approved", "preview", "published", "archived")
+TRANSITIONS = {"draft": {"review"}, "review": {"draft", "approved"},
+               "approved": {"preview", "published", "draft"},
+               "preview": {"approved", "published"}, "published": {"archived"}, "archived": set()}
+SLUG_WORD = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def slug_part(value: str) -> str:
+    value = re.sub(r"[^a-z0-9]+", "-", value.strip().lower()).strip("-")
+    if not value or not SLUG_WORD.fullmatch(value):
+        raise ValueError("slug parts must contain lowercase ASCII words")
+    return value
+
+
+def variant_slug(kind: str, *, location: str = "", event: str = "", holiday: str = "") -> str:
+    if kind not in VARIANT_TYPES:
+        raise ValueError("variant type must be location, event, or holiday")
+    value = {"location": location, "event": event, "holiday": holiday}[kind]
+    if not value:
+        raise ValueError(f"{kind} variant requires its slug part")
+    return f"{kind}/{slug_part(value)}"
+
+
+def similarity(source: str, variant: str) -> float:
+    left, right = set(re.findall(r"[a-z0-9]+", source.lower())), set(re.findall(r"[a-z0-9]+", variant.lower()))
+    return 1.0 if not left and not right else len(left & right) / max(1, len(left | right))
+
+
+class ServiceVariantStore:
+    def __init__(self, path: Path):
+        self.path = path.resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.data = {"schemaVersion": "maggie-service-variants.v1", "variants": [], "redirects": [], "events": []}
+        if self.path.exists():
+            self.data = json.loads(self.path.read_text(encoding="utf-8"))
+        if self.data.get("schemaVersion") != "maggie-service-variants.v1":
+            raise ValueError("unsupported service variant store")
+
+    def _save(self) -> None:
+        self.path.write_text(json.dumps(self.data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    def _event(self, action: str, variant_id: str, actor: str, reason: str) -> None:
+        self.data["events"].append({"action": action, "variantId": variant_id, "actor": actor, "reason": reason, "at": now()})
+
+    def _find(self, variant_id: str) -> dict:
+        found = next((item for item in self.data["variants"] if item["id"] == variant_id), None)
+        if not found:
+            raise ValueError("service variant not found")
+        return found
+
+    def create(self, *, service_id: str, variant_id: str, variant_type: str, locale: str, market: str,
+               slug: str, title: str, facts: list[dict], source_revision: str, canonical_variant_id: str | None = None,
+               cluster_links: list[str] | None = None, layout_family: str = "service-default", actor: str = "cli") -> dict:
+        if not service_id or not variant_id or not locale or not market or not title or not source_revision:
+            raise ValueError("service identity, locale, market, title and source revision are required")
+        if variant_type not in VARIANT_TYPES or not SLUG_WORD.fullmatch(slug.split("/", 1)[-1]) or not slug.startswith(variant_type + "/"):
+            raise ValueError("slug must match the canonical variant type/slug grammar")
+        if not isinstance(facts, list) or not facts or any(not isinstance(item, dict) or not item.get("key") or not item.get("value") for item in facts):
+            raise ValueError("variant requires meaningful keyed facts")
+        if any(item["id"] == variant_id for item in self.data["variants"]):
+            raise ValueError("variant ID already exists")
+        if any(item["slug"] == slug and item["locale"] == locale for item in self.data["variants"]):
+            raise ValueError("variant slug and locale collision")
+        if canonical_variant_id and not any(item["id"] == canonical_variant_id for item in self.data["variants"]):
+            raise ValueError("canonical variant does not exist")
+        item = {"id": variant_id, "serviceId": service_id, "variantType": variant_type, "locale": locale,
+                "market": market, "slug": slug, "title": title, "facts": facts,
+                "clusterLinks": sorted(set(cluster_links or [])), "layoutFamily": layout_family,
+                "canonicalVariantId": canonical_variant_id or variant_id, "canonicalUrl": "/services/" + slug + "/",
+                "hreflang": {locale: "/services/" + slug + "/"}, "sourceRevision": source_revision,
+                "provenance": {"operation": "create", "actor": actor, "sourceRevision": source_revision},
+                "status": "draft", "createdAt": now(), "updatedAt": now()}
+        self.data["variants"].append(item); self._event("variant.created", variant_id, actor, "draft created"); self._save()
+        return item
+
+    def edit(self, variant_id: str, *, title: str, facts: list[dict], source_revision: str, actor: str, reason: str) -> dict:
+        item = self._find(variant_id)
+        if item["status"] not in {"draft", "review"}:
+            raise ValueError("only draft or review variants may be edited")
+        if not title or not facts:
+            raise ValueError("edited variant requires title and facts")
+        item.update(title=title, facts=facts, sourceRevision=source_revision, updatedAt=now())
+        item["provenance"].update({"operation": "edit", "actor": actor, "reason": reason, "sourceRevision": source_revision})
+        self._event("variant.edited", variant_id, actor, reason); self._save(); return item
+
+    def translate(self, source_id: str, *, variant_id: str, locale: str, market: str, title: str,
+                  facts: list[dict], source_revision: str, actor: str) -> dict:
+        source = self._find(source_id)
+        return self.create(service_id=source["serviceId"], variant_id=variant_id, variant_type=source["variantType"],
+            locale=locale, market=market, slug=source["slug"], title=title, facts=facts,
+            source_revision=source_revision, canonical_variant_id=source["canonicalVariantId"],
+            cluster_links=source["clusterLinks"], layout_family=source["layoutFamily"], actor=actor)
+
+    def transition(self, variant_id: str, target: str, actor: str, reason: str, *, preview_url: str | None = None) -> dict:
+        item = self._find(variant_id)
+        if target not in STATUSES or target not in TRANSITIONS[item["status"]]:
+            raise ValueError(f"invalid variant transition: {item['status']} -> {target}")
+        if target == "preview":
+            if not preview_url or not preview_url.startswith(("http://", "https://", "file://")):
+                raise ValueError("preview requires a rendered preview URL")
+            item["previewUrl"] = preview_url
+        if target == "published":
+            if not item.get("canonicalUrl") or not item.get("hreflang") or not item.get("facts"):
+                raise ValueError("published variant requires canonical, hreflang and facts")
+            if item.get("canonicalVariantId") != item["id"] and not any(v["id"] == item["canonicalVariantId"] and v["status"] == "published" for v in self.data["variants"]):
+                raise ValueError("canonical source must be published before a translated variant")
+        old = item["status"]; item["status"] = target; item["updatedAt"] = now()
+        item.setdefault("approval", []).append({"from": old, "to": target, "actor": actor, "reason": reason, "at": now()})
+        self._event("variant." + target, variant_id, actor, reason); self._save(); return item
+
+    def plan_slug_change(self, variant_id: str, new_slug: str, actor: str) -> dict:
+        item = self._find(variant_id)
+        if item["status"] == "published" and not actor:
+            raise ValueError("published URL changes require owner approval")
+        if not new_slug.startswith(item["variantType"] + "/") or not SLUG_WORD.fullmatch(new_slug.split("/", 1)[-1]):
+            raise ValueError("new slug violates variant grammar")
+        if any(v["slug"] == new_slug and v["locale"] == item["locale"] for v in self.data["variants"] if v["id"] != variant_id):
+            raise ValueError("new slug collides with another variant")
+        redirect = {"from": item["canonicalUrl"], "to": "/services/" + new_slug + "/", "ownerApproval": actor, "status": "planned"}
+        self.data["redirects"].append(redirect); self._save(); return redirect
+
+    def validate(self, variant_id: str, source_text: str | None = None, render_report: dict | None = None) -> dict:
+        item = self._find(variant_id); errors = []
+        if not item["clusterLinks"] and item["variantType"] != "location": errors.append("cluster links required")
+        if source_text is not None and similarity(source_text, item["title"] + " " + " ".join(str(f["value"]) for f in item["facts"])) < 0.1:
+            errors.append("variant content has no meaningful similarity to source")
+        if item["canonicalVariantId"] != item["id"] and item["canonicalVariantId"] not in {v["id"] for v in self.data["variants"]}: errors.append("canonical relation missing")
+        if render_report is not None:
+            if render_report.get("schemaVersion") != "maggie-service-variant-render.v1" or render_report.get("passed") is not True:
+                errors.append("render report is not passed")
+            if render_report.get("layoutFamily") != item["layoutFamily"]:
+                errors.append("rendered layout family does not match variant contract")
+            if render_report.get("canonicalUrl") != item["canonicalUrl"]:
+                errors.append("rendered canonical URL does not match variant contract")
+            if render_report.get("locale") != item["locale"]:
+                errors.append("rendered locale does not match variant contract")
+        return {"passed": not errors, "errors": errors, "similarity": similarity(source_text, item["title"]) if source_text is not None else None,
+                "layoutFamily": item["layoutFamily"], "status": item["status"]}

package/bundled-tools/runtime/site_baseline.py

@@ -0,0 +1,60 @@
+"""Reviewed static-site contracts. Never silently accept a changed baseline."""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def snapshot(report: dict, reviewer: str) -> dict:
+    if not reviewer.strip():
+        raise ValueError("baseline requires a reviewer")
+    crawl = report.get("crawl", {})
+    if not report.get("passed") or not crawl.get("enabled") or not crawl.get("complete"):
+        raise ValueError("baseline requires a passing, complete sitemap crawl")
+    pages = crawl.get("pages", [])
+    if not pages or len(pages) != crawl.get("discovered_url_count"):
+        raise ValueError("baseline page coverage is incomplete")
+    contracts = {}
+    for page in pages:
+        if not page.get("passed") or not isinstance(page.get("contract"), dict):
+            raise ValueError("baseline requires successful page contracts")
+        if page["url"] in contracts:
+            raise ValueError("duplicate page URL")
+        contracts[page["url"]] = page["contract"]
+    return {"schemaVersion": "maggie-site-baseline.v1", "url": report["url"],
+            "reviewer": reviewer.strip(), "createdAt": datetime.now(timezone.utc).isoformat(),
+            "pages": contracts}
+
+
+def compare(baseline: dict, report: dict) -> dict:
+    if baseline.get("schemaVersion") != "maggie-site-baseline.v1" or not isinstance(baseline.get("pages"), dict) or not baseline["pages"]:
+        raise ValueError("invalid site baseline")
+    crawl = report.get("crawl", {})
+    errors = []
+    if baseline.get("url") != report.get("url"):
+        errors.append("site origin/base URL differs from baseline")
+    if not crawl.get("enabled") or not crawl.get("complete"):
+        errors.append("complete sitemap crawl required")
+    current = {page["url"]: page.get("contract") for page in crawl.get("pages", [])}
+    expected = baseline["pages"]
+    added, removed = sorted(current.keys() - expected.keys()), sorted(expected.keys() - current.keys())
+    changes = []
+    for url in sorted(expected.keys() & current.keys()):
+        actual = current[url]
+        if not isinstance(actual, dict):
+            errors.append("missing page contract: " + url)
+            continue
+        fields = sorted(key for key in expected[url].keys() | actual.keys() if expected[url].get(key) != actual.get(key))
+        if fields:
+            changes.append({"url": url, "fields": fields})
+    return {"passed": not errors and not added and not removed and not changes,
+            "errors": errors, "added": added, "removed": removed, "changed": changes}
+
+
+def save(path: Path, baseline: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Exclusive creation protects the reviewed baseline from accidental replacement.
+    with path.open("x", encoding="utf-8") as stream:
+        json.dump(baseline, stream, ensure_ascii=False, indent=2)
+        stream.write("\n")

package/package.json

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

package/references/blog-translation-ingestion.md

@@ -0,0 +1,52 @@
+# Blog translation ingestion contract
+
+## Entry points and ownership
+
+List every ingest entry point before enabling automatic translation: manual
+CLI, admin HTTP action, scheduled tick, webhook and backfill. Each must use
+the same post-persistence scheduling function. Record the caller and source
+revision in the run evidence. A hook in a standalone script is insufficient
+evidence for a scheduled HTTP path.
+
+The packaged Python BlogStore reconciles durable translation tasks after source
+persistence when `autoTranslateEnabled` is true and `translationLocales` contains
+supported locale tags. The same reconciliation runs before translation retries,
+so an interruption between source persistence and scheduling is recoverable.
+Tasks are under `.maggie/blog/translations/`; content changes create new task
+identities, and only current identities are processed. Old drafts are retained
+for inspection, not eligible for automatic publication.
+
+Run `maggie blog translate-pending --project . --adapter-command
+'["python3", "scripts/translation-provider.py"]' --confirm` to generate drafts
+from saved sources without re-pulling. The project supplies a trusted adapter
+using the localization provider protocol. It receives title, excerpt, body,
+topic labels and supplied image alt text. Completed tasks are skipped; failures
+return partial/nonzero and store only an error category. Use one worker per
+project. Host database/API schedulers must explicitly integrate this boundary;
+installing the skill does not patch an existing host ingestion implementation.
+
+## Durable work
+
+After source persistence, enqueue translation work using an idempotency key
+of project, content ID, source revision, target locale and operation. The
+source write and scheduling intent must commit together or use a reconciliation
+pass that detects missing intents. A repeat pull must retry pending/failed
+translation without purchasing another upstream pull or duplicating completed
+work. A changed source revision invalidates earlier translation work.
+
+Track pending, running, succeeded and failed states with attempt count and
+safe error category. A run with failed required translations is partial, not
+completed. Missing credentials or provider availability must be visible;
+never print credentials or provider payloads in the report. Keep translated
+content draft and non-indexable until its validation and review pass.
+
+## Acceptance evidence
+
+Exercise the actual CLI and scheduled HTTP entry points against fixture
+providers. With translation enabled, both must schedule identical work for
+the same source revision. With translation disabled, neither schedules work.
+Test provider failure, process interruption, retry without re-pull, duplicate
+delivery, changed source revision, multiple target locales, media alt text and
+topic labels. Assert persisted target output and queue state, not merely the
+presence of a translate function name. Browser preview must show the target
+locale before publication is claimed complete.