@topy-ai/maggie 0.6.8 → 0.7.0

package/bundled-tools/clis/maggie_design.py

@@ -526,6 +526,18 @@ def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
             project / "src" / "app" / relative / "page.tsx",
         ]
         match = next((path for path in candidates if path.is_file()), None)
+        if not match:
+            # Dynamic catch-all routes are the source of truth for many page
+            # families; a concrete URL still needs to resolve to that route
+            # before an in-place design job can be created.
+            roots = [project / "src" / "pages", project / "src" / "app"]
+            catchalls = {"[...slug]", "[[...slug]]"}
+            for root in roots:
+                if not root.is_dir():
+                    continue
+                match = next((path for path in root.rglob("*") if path.is_file() and path.stem in catchalls), None)
+                if match:
+                    break
         if not match:
             raise ValueError(f"existing route required for in-place redesign: {route}")
         resolved_routes.append({"route": value, "source": str(match)})

package/bundled-tools/clis/maggie_localization.py

@@ -13,6 +13,27 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from content_localization import LANGUAGES, MARKETS, OPERATIONS, parse_locale, protected_field_changes, stale, valid_locale, validate_translation
+from localization_runner import generate, process_adapter
+
+
+def generate_job(args: argparse.Namespace) -> int:
+    if not args.confirm:
+        raise ValueError("generate requires --confirm: the adapter receives source text and may incur provider costs")
+    command = json.loads(args.adapter_command)
+    adapter = process_adapter(command, args.project, args.timeout)
+    job = load(args.job)
+    errors = validate_job(args.job, args.source)["errors"]
+    if errors:
+        raise ValueError("; ".join(errors))
+    source = load(args.source)
+    contract = {key: job.get(key) for key in (
+        "jobId", "contentId", "sourceRevision", "sourceLanguage", "targetLanguage",
+        "targetLocale", "market", "operation", "generationContract")}
+
+    state = generate(source["strings"], contract, args.output, adapter, args.character_budget)
+    print(json.dumps({"status": state["status"], "strings": len(state["translations"]),
+                      "output": str(args.output), "publish": False}))
+    return 0
 
 
 def now() -> str:
@@ -186,6 +207,12 @@ def plan_job(args: argparse.Namespace) -> int:
         "targetLanguage": args.target_lang,
         "targetLocale": args.locale,
         "operation": args.operation,
+        "generationContract": {
+            "mode": args.operation,
+            "preserveMeaning": args.operation in {"translate", "polish", "localise", "rebrand"},
+            "allowStructuralRewrite": args.operation in {"rewrite", "rebrand"},
+            "marketAdaptation": args.operation in {"localise", "rebrand"},
+        },
         "translationGroupId": identity.get("translationGroupId", f"tg-{content_id}"),
         "sourceRevision": args.source_revision or (source_artifact or {}).get("sourceRevision") or content.get("sourceRevision", "unknown"),
         "status": "draft",
@@ -218,6 +245,11 @@ def validate_job(path: Path, source_path: Path | None = None, render_path: Path
     if not valid_locale(job.get("targetLocale")) or parse_locale(job.get("targetLocale"))[0] != job.get("targetLanguage"):
         errors.append("targetLocale must be a supported tag matching targetLanguage")
     translation = job.get("translation", {})
+    generation = job.get("generationContract", {})
+    if generation.get("mode") and generation.get("mode") != job.get("operation"):
+        errors.append("generationContract mode must match operation")
+    if job.get("operation") == "rewrite" and not generation.get("allowStructuralRewrite"):
+        errors.append("rewrite requires structural rewrite permission")
     errors.extend(validate_translation({
         "contentId": job.get("contentId"), "lang": job.get("targetLanguage"),
         "locale": job.get("targetLocale"), "translationGroupId": job.get("translationGroupId", f"tg-{job.get('contentId')}"),
@@ -307,6 +339,15 @@ def glossary(project: Path) -> int:
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     sub = parser.add_subparsers(dest="command", required=True)
+    generate_parser = sub.add_parser("generate", help="Generate resumable draft strings using a trusted provider process")
+    generate_parser.add_argument("job", type=Path)
+    generate_parser.add_argument("--project", type=Path, default=Path("."))
+    generate_parser.add_argument("--source", type=Path, required=True)
+    generate_parser.add_argument("--output", type=Path, required=True)
+    generate_parser.add_argument("--adapter-command", required=True, help="JSON argv array; executed without a shell")
+    generate_parser.add_argument("--character-budget", type=int, default=8000)
+    generate_parser.add_argument("--timeout", type=int, default=120)
+    generate_parser.add_argument("--confirm", action="store_true")
     plan_parser = sub.add_parser("plan")
     plan_parser.add_argument("--project", type=Path, default=Path("."))
     plan_parser.add_argument("--content", type=Path, required=True)
@@ -335,6 +376,7 @@ def main() -> int:
         command = sub.add_parser(name); command.add_argument("--project", type=Path, default=Path("."))
     args = parser.parse_args()
     try:
+        if args.command == "generate": return generate_job(args)
         if args.command == "plan": return plan_job(args)
         if args.command == "preview": return preview(args.job)
         if args.command == "validate":

package/bundled-tools/clis/maggie_memory.py

@@ -13,6 +13,9 @@ from runtime import maggie_memory as memory
 
 
 def output(value: object) -> None:
+    if isinstance(value, dict) and value.get("status") == "candidate" and value.get("id"):
+        value = dict(value)
+        value["notice"] = "Saved as candidate; excluded from search/context until reviewed and transitioned to active. Inspect with: maggie memory list --status candidate"
     print(json.dumps(value, indent=2, ensure_ascii=False))
 
 
@@ -82,7 +85,7 @@ def main() -> int:
             output(memory.transition(args.project, args.kind, args.item_id, args.status))
         elif args.command in {"context", "search", "list"}:
             query = args.query if args.command == "search" else getattr(args, "query", "")
-            result = memory.relevant(args.project, skill=getattr(args, "skill", ""), query=query)
+            result = memory.relevant(args.project, skill=getattr(args, "skill", ""), query=query, status=getattr(args, "status", None))
             if args.command == "list" and args.kind:
                 result = {args.kind: result[args.kind]}
             if args.command == "list" and args.status:

package/bundled-tools/clis/maggie_service_booking.py

@@ -793,9 +793,9 @@ def cmd_match_pages_review(args):
         out=project/".maggie"/"booking"/"page-matches.json"; out.parent.mkdir(parents=True,exist_ok=True); (project/"docs").mkdir(parents=True,exist_ok=True); payload={"matchedAt":NOW(),"requiresManualSelection":True,"candidateServices":report,"selected":0,"conflicts":conflicts}; out.write_text(json.dumps(payload,indent=2,ensure_ascii=False)+"\n",encoding="utf-8"); (project/"docs"/"service-page-matches.json").write_text(json.dumps(payload,indent=2,ensure_ascii=False)+"\n",encoding="utf-8"); print(json.dumps({"status":"conflict-review","pagesScanned":len(candidates),"servicesScanned":len(report),"selected":0,"conflicts":conflicts,"report":str(out)},indent=2)); return 1
     for service,path_value in selected:
         relation={"path":path_value,"role":"canonical","matchMethod":"manual-selection","confidence":1.0}; service["pages"]=[p for p in service.get("pages",[]) if p.get("path")!=path_value]+[relation]
-    candidate_paths={c["path"] for c in candidates}
-    for service in data.get("services",[]):
-        service["pages"]=[p for p in service.get("pages",[]) if p.get("role")!="supporting" or p.get("path") in candidate_paths]
+    # Reviewed selections must not erase existing supporting relations. They
+    # may have been imported from a route table or authored intentionally even
+    # when the current page scanner cannot see their source file.
     out=project/".maggie"/"booking"/"page-matches.json"; payload={"matchedAt":NOW(),"requiresManualSelection":True,"candidateServices":report,"selected":len(selected),"conflicts":[]}; out.parent.mkdir(parents=True,exist_ok=True); (project/"docs").mkdir(parents=True,exist_ok=True); out.write_text(json.dumps(payload,indent=2,ensure_ascii=False)+"\n",encoding="utf-8"); (project/"docs"/"service-page-matches.json").write_text(json.dumps(payload,indent=2,ensure_ascii=False)+"\n",encoding="utf-8"); save(project,data); print(json.dumps({"status":"review-required","pagesScanned":len(candidates),"servicesScanned":len(report),"selected":len(selected),"conflicts":[],"report":str(out)},indent=2)); return 0
 def cmd_run(args):
     project=root(args); job={"workflow":"maggie-service-booking","phase":"created","source":args.source,"provider":args.provider,"startedAt":NOW(),"history":[]}

package/bundled-tools/clis/site_audit.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import re
 import sys
@@ -15,6 +16,7 @@ from urllib.request import Request, urlopen
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from content_localization import MARKETS, parse_locale, valid_locale  # noqa: E402
+import site_baseline
 
 
 class PageParser(HTMLParser):
@@ -32,13 +34,27 @@ class PageParser(HTMLParser):
         self._jsonld = None
         self.images = []
         self.hreflang = []
+        self.robots_directives = []
+        self.structure = []
+        self.visible_text = []
+        self.hidden_depth = 0
+        self.templates = set()
 
     def handle_starttag(self, tag, attrs):
         data = dict(attrs)
+        if data.get("data-template"):
+            self.templates.add(data["data-template"])
+        if tag in {"script", "style", "noscript"}:
+            self.hidden_depth += 1
+        if not self.hidden_depth:
+            self.structure.append(["start", tag, {key: data[key] for key in
+                ("class", "id", "role", "href", "src", "data-template", "data-section", "data-i18n") if key in data}])
         if tag == "html":
             self.lang = data.get("lang", "")
         if tag == "meta" and data.get("name"):
             self.meta[data["name"].lower()] = data.get("content", "")
+            if data["name"].lower() == "robots":
+                self.robots_directives.append(data.get("content", "").lower())
         if tag == "meta" and data.get("property"):
             self.meta[data["property"].lower()] = data.get("content", "")
         if tag == "title":
@@ -58,6 +74,10 @@ class PageParser(HTMLParser):
             self.images.append({"src": data.get("src", ""), "alt": data.get("alt")})
 
     def handle_endtag(self, tag):
+        if tag in {"script", "style", "noscript"}:
+            self.hidden_depth = max(0, self.hidden_depth - 1)
+        elif not self.hidden_depth:
+            self.structure.append(["end", tag])
         if tag == "title":
             self.in_title = False
         if tag == "script" and self._jsonld is not None:
@@ -69,23 +89,35 @@ class PageParser(HTMLParser):
             self._jsonld = None
 
     def handle_data(self, data):
+        if not self.hidden_depth and data.strip():
+            self.visible_text.append(" ".join(data.split()))
         if self.in_title:
             self.title += data.strip()
         if self._jsonld is not None:
             self._jsonld.append(data)
 
 
-def fetch(url: str) -> tuple[int, str, str]:
+def fetch(url: str, evidence: dict | None = None) -> tuple[int, str, str]:
     request = Request(url, headers={"User-Agent": "AI-CMO-Skills-Audit/0.1"})
     with urlopen(request, timeout=15) as response:
-        body = response.read(2_000_000).decode("utf-8", "replace")
+        raw = response.read(2_000_001)
+        if len(raw) > 2_000_000:
+            raise ValueError("response exceeds audit size limit")
+        body = raw.decode(response.headers.get_content_charset() or "utf-8", "replace")
+        if evidence is not None:
+            evidence.update({"finalUrl": response.geturl(),
+                             "xRobotsTag": response.headers.get_all("X-Robots-Tag", [])})
         return response.status, response.headers.get_content_type(), body
 
 
-def audit_page(url: str, html: str, status: int, content_type: str, expected_languages: set[str] | None = None) -> dict:
+def audit_page(url: str, html: str, status: int, content_type: str, expected_languages: set[str] | None = None, response_evidence: dict | None = None) -> dict:
     page = PageParser()
     page.feed(html)
     canonical = urljoin(url, page.canonical) if page.canonical else ""
+    response_evidence = response_evidence or {"finalUrl": url, "xRobotsTag": []}
+    robots = page.robots_directives + [value.lower() for value in response_evidence["xRobotsTag"]]
+    robots_tokens = [token.strip() for directive in robots for token in directive.split(",")]
+    robots_tokens = [token.rsplit(":", 1)[-1].strip() for token in robots_tokens]
     return {
         "url": url,
         "status": status,
@@ -104,10 +136,45 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
         "canonical_value": canonical,
         "image_count": len(page.images),
         "language": parse_locale(page.lang)[0],
+        "declaredLocale": page.lang,
+        "template": next(iter(page.templates)) if len(page.templates) == 1 else "unknown",
+        "evidence": {"structural": "captured", "rendered": "not_run", "behavioral": "not_run"},
         "hreflang": page.hreflang,
+        "contract": {
+            "response": response_evidence,
+            "title": page.title, "meta": page.meta, "canonical": canonical,
+            "lang": page.lang, "hreflang": page.hreflang, "robots": robots,
+            "jsonld": page.jsonld_values, "images": page.images,
+            "structureHash": hashlib.sha256(json.dumps(page.structure, sort_keys=True).encode()).hexdigest(),
+            "textHash": hashlib.sha256(" ".join(page.visible_text).encode()).hexdigest(),
+        },
+        "robots": not robots or not any(token in {"noindex", "none", "nofollow"} for token in robots_tokens),
+        "robots_directives": robots,
+        "robots_conflict": len({token for token in robots_tokens if token in {"index", "noindex", "follow", "nofollow", "none"}} & {"index", "noindex"}) > 1 or len({token for token in robots_tokens if token in {"follow", "nofollow", "none"}} & {"follow", "nofollow"}) > 1,
     }
 
 
+def summarize_crawl(pages: list[dict]) -> dict:
+    """Count captured evidence, preserving regional/script locale distinctions."""
+    groups = {}
+    for page in pages:
+        locale = page.get("declaredLocale") or "unknown"
+        template = page.get("template") or "unknown"
+        key = (locale, template)
+        group = groups.setdefault(key, {"locale": locale, "template": template,
+            "total": 0, "passed": 0, "failed": 0, "failedUrls": [],
+            "evidence": {"structural": "captured", "rendered": "not_run", "behavioral": "not_run"}})
+        group["total"] += 1
+        if page.get("passed") is True:
+            group["passed"] += 1
+        else:
+            group["failed"] += 1
+            group["failedUrls"].append(page["url"])
+    for group in groups.values():
+        group["failedUrls"].sort()
+    return {"byLocaleTemplate": [groups[key] for key in sorted(groups)]}
+
+
 def language_set(value: str | None) -> set[str]:
     if not value:
         return set()
@@ -170,7 +237,17 @@ def main() -> int:
     parser.add_argument("--markets", help="comma-separated markets: global,uk,us")
     parser.add_argument("--check-hreflang", action="store_true")
     parser.add_argument("--check-translation-completeness", action="store_true")
+    baseline_args = parser.add_mutually_exclusive_group()
+    baseline_args.add_argument("--save-baseline", type=Path, help="create a new reviewed contract from a passing complete crawl")
+    baseline_args.add_argument("--baseline", type=Path, help="fail on differences from a reviewed contract")
+    parser.add_argument("--reviewer", help="required for --save-baseline")
     args = parser.parse_args()
+    if args.max_pages < 1:
+        parser.error("max-pages must be positive")
+    if (args.save_baseline or args.baseline) and not args.crawl:
+        parser.error("baseline operations require --crawl")
+    if args.save_baseline and not (args.reviewer or "").strip():
+        parser.error("save-baseline requires --reviewer")
     try:
         expected_languages = language_set(args.languages)
         markets = {item.strip() for item in (args.markets or "").split(",") if item.strip()}
@@ -197,6 +274,9 @@ def main() -> int:
         checks["jsonld"] = {"ok": page.jsonld > 0 and all(item is not None for item in page.jsonld_values), "count": page.jsonld}
         checks["entity_jsonld"] = {"ok": any(isinstance(item, dict) and item.get("@type") and (item.get("url") or item.get("@id")) for item in page.jsonld_values), "count": page.jsonld}
         checks["crawlable_links"] = {"ok": page.anchors > 0, "count": page.anchors}
+        robots_tokens = [token.strip() for directive in page.robots_directives for token in directive.split(",")]
+        checks["robots_directive"] = {"ok": not page.robots_directives or not any(token in {"noindex", "none", "nofollow"} for token in robots_tokens), "directives": page.robots_directives}
+        checks["robots_conflict"] = {"ok": not (len({token for token in robots_tokens if token in {"index", "noindex"}}) > 1 or len({token for token in robots_tokens if token in {"follow", "nofollow"}}) > 1), "directives": page.robots_directives}
         if args.check_hreflang or args.check_translation_completeness:
             checks["hreflang"] = hreflang_check(base, page, expected_languages) if args.check_hreflang else {"ok": True, "links": page.hreflang}
             if args.check_translation_completeness and expected_languages:
@@ -221,11 +301,14 @@ def main() -> int:
     if args.crawl:
         try:
             urls, sitemap_violations = sitemap_urls(base)
+            crawl["discovered_url_count"] = len(urls)
+            crawl["complete"] = len(urls) <= args.max_pages and not sitemap_violations
             urls = urls[: args.max_pages]
             for page_url in urls:
                 try:
-                    status, content_type, body = fetch(page_url)
-                    page_checks = audit_page(page_url, body, status, content_type, expected_languages)
+                    response_evidence = {}
+                    status, content_type, body = fetch(page_url, response_evidence)
+                    page_checks = audit_page(page_url, body, status, content_type, expected_languages, response_evidence)
                     if args.check_hreflang or args.check_translation_completeness:
                         parsed = PageParser(); parsed.feed(body)
                         page_checks["hreflang_check"] = hreflang_check(page_url, parsed, expected_languages) if args.check_hreflang else {"ok": True, "links": parsed.hreflang}
@@ -233,18 +316,30 @@ def main() -> int:
                             page_checks["translation_completeness"] = {"ok": all(lang in {item["lang"] for item in parsed.hreflang} for lang in expected_languages), "expected": sorted(expected_languages)}
                     page_checks["passed"] = all(
                         page_checks[key]
-                        for key in ("ok", "title", "h1", "canonical", "description", "locale", "open_graph", "twitter_card", "jsonld", "entity_jsonld", "images")
-                    ) and (not args.check_hreflang or page_checks["hreflang_check"]["ok"]) and (not args.check_translation_completeness or page_checks.get("translation_completeness", {}).get("ok", False))
+                        for key in ("ok", "title", "h1", "canonical", "description", "locale", "open_graph", "twitter_card", "jsonld", "entity_jsonld", "images", "robots")
+                    ) and not page_checks["robots_conflict"] and (not args.check_hreflang or page_checks["hreflang_check"]["ok"]) and (not args.check_translation_completeness or page_checks.get("translation_completeness", {}).get("ok", False))
                 except Exception as exc:
                     page_checks = {"url": page_url, "passed": False, "error": type(exc).__name__}
                 crawl["pages"].append(page_checks)
             crawl["sitemap_loc_violations"] = sitemap_violations
-            crawl["passed"] = not sitemap_violations and bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
+            crawl["passed"] = crawl["complete"] and bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
             crawl["url_count"] = len(urls)
         except Exception as exc:
             crawl = {"enabled": True, "passed": False, "error": type(exc).__name__, "pages": []}
 
     result = {"url": base, "environment": args.environment, "checks": checks, "crawl": crawl, "passed": all(v.get("ok", False) for v in checks.values()) and crawl["passed"]}
+    result["evidence"] = {"structural": "captured", "rendered": "not_run", "behavioral": "not_run"}
+    crawl["summary"] = summarize_crawl(crawl["pages"])
+    try:
+        if args.baseline:
+            result["baseline"] = site_baseline.compare(json.loads(args.baseline.read_text()), result)
+            result["passed"] = result["passed"] and result["baseline"]["passed"]
+        if args.save_baseline:
+            site_baseline.save(args.save_baseline, site_baseline.snapshot(result, args.reviewer))
+            result["baseline"] = {"passed": True, "saved": str(args.save_baseline)}
+    except (OSError, ValueError, TypeError) as exc:
+        result["baseline"] = {"passed": False, "error": str(exc)}
+        result["passed"] = False
     if args.output:
         output = Path(args.output).resolve()
         output.parent.mkdir(parents=True, exist_ok=True)

package/bundled-tools/runtime/browser_behavior.py

@@ -0,0 +1,35 @@
+"""Compare actual browser samples against explicit route expectations."""
+
+
+def validate_samples(samples: list[dict], selectors: list[str], sticky: list[str]) -> dict:
+    errors = []
+    if len(samples) < 2:
+        return {"passed": False, "errors": ["at least two scroll samples required"]}
+    first = samples[0]
+    for sample in samples:
+        if sample.get("viewport") != first.get("viewport") or sample.get("url") != first.get("url"):
+            errors.append("samples must share URL and viewport")
+        if sample.get("horizontalOverflow"):
+            errors.append("horizontal overflow")
+        elements = {element["selector"]: element for element in sample.get("elements", [])}
+        for selector in selectors:
+            element = elements.get(selector, {})
+            if not element.get("found") or not element.get("visible"):
+                errors.append(f"required element missing or hidden: {selector}")
+    if samples[-1].get("scroll", {}).get("y", 0) <= first.get("scroll", {}).get("y", 0):
+        errors.append("scroll did not advance; behavior unverified")
+    for selector in sticky:
+        for sample in samples[1:]:
+            element = next((item for item in sample.get("elements", []) if item.get("selector") == selector), {})
+            if element.get("position") not in {"sticky", "fixed"}:
+                errors.append(f"expected sticky/fixed positioning: {selector}")
+                continue
+            top = element.get("rect", {}).get("top")
+            try:
+                inset = float(element.get("insetTop", "auto").removesuffix("px"))
+            except (ValueError, AttributeError):
+                errors.append(f"sticky top inset unmeasurable: {selector}")
+                continue
+            if not isinstance(top, (int, float)) or abs(top - inset) > 2:
+                errors.append(f"sticky element left expected top inset: {selector}")
+    return {"passed": not errors, "errors": sorted(set(errors))}

package/bundled-tools/runtime/browser_geometry.js

@@ -0,0 +1,31 @@
+// Read-only browser measurements. The caller supplies selectors and scrolls
+// between samples; never infer scrolling behavior from position:sticky alone.
+((selectors = window.__maggieAuditSelectors || []) => {
+  const visible = element => {
+    const rect = element.getBoundingClientRect();
+    if (!rect.width || !rect.height) return false;
+    for (let node = element; node; node = node.parentElement) {
+      const style = getComputedStyle(node);
+      if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0) return false;
+    }
+    return true;
+  };
+  return {
+    url: location.href,
+    viewport: {width: innerWidth, height: innerHeight},
+    scroll: {x: scrollX, y: scrollY, maxY: Math.max(0, document.documentElement.scrollHeight - innerHeight)},
+    horizontalOverflow: document.documentElement.scrollWidth > innerWidth + 1,
+    elements: selectors.map(selector => {
+      const element = document.querySelector(selector);
+      if (!element) return {selector, found: false, visible: false};
+      const rect = element.getBoundingClientRect();
+      const style = getComputedStyle(element);
+      const parent = element.parentElement?.getBoundingClientRect();
+      return {selector, found: true, visible: visible(element),
+        rect: {top: rect.top, bottom: rect.bottom, left: rect.left, right: rect.right, width: rect.width, height: rect.height},
+        position: style.position, insetTop: style.top,
+        parentRect: parent ? {top: parent.top, bottom: parent.bottom, height: parent.height} : null,
+        hiddenDescendants: [...element.querySelectorAll('a,button,input,select')].filter(child => !visible(child)).length};
+    })
+  };
+})()

package/bundled-tools/runtime/localization_runner.py

@@ -0,0 +1,113 @@
+"""Resumable translation batches; provider calls are supplied by the adapter."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def process_adapter(command: list[str], project: Path, timeout: int = 120):
+    if not isinstance(command, list) or not command or any(not isinstance(part, str) or not part for part in command):
+        raise ValueError("adapter-command must be a nonempty JSON argv array")
+    if timeout < 1:
+        raise ValueError("timeout must be positive")
+    def adapter(batch, contract):
+        try:
+            result = subprocess.run(command, input=json.dumps({
+                "schemaVersion": "maggie-provider-request.v1", "strings": batch,
+                "contract": contract}, ensure_ascii=False), text=True, capture_output=True,
+                timeout=timeout, check=False, cwd=project.resolve())
+        except (OSError, subprocess.TimeoutExpired):
+            raise OSError("provider adapter could not execute or timed out; retry to resume") from None
+        if result.returncode:
+            raise OSError("provider adapter failed; retry to resume (provider logs suppressed)")
+        return result.stdout
+    return adapter
+
+
+def checkpoint(path: Path, state: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, name = tempfile.mkstemp(prefix=".translation-", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            json.dump(state, stream, ensure_ascii=False, indent=2)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        if os.path.exists(name):
+            os.unlink(name)
+
+
+def generate(strings: list[dict], contract: dict, output: Path, adapter,
+             character_budget: int = 8000) -> dict:
+    """Adapter accepts (batch, contract) and returns an exact ID-to-text map.
+
+    Invalid/truncated output splits a batch. Provider exceptions propagate;
+    successfully checkpointed batches are reusable on the next invocation.
+    """
+    if type(character_budget) is not int or character_budget < 1:
+        raise ValueError("character_budget must be positive")
+    if not strings or any(not isinstance(item, dict) or not isinstance(item.get("id"), str)
+                          or not item["id"] or not isinstance(item.get("text"), str)
+                          or not item["text"].strip() for item in strings):
+        raise ValueError("source strings require nonempty IDs and text")
+    if len({item["id"] for item in strings}) != len(strings):
+        raise ValueError("duplicate source IDs")
+    identity = hashlib.sha256(json.dumps({"strings": strings, "contract": contract},
+                                        sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+    state = {"schemaVersion": "maggie-generation.v1", "identity": identity,
+             "translations": {}, "status": "pending", "publish": False}
+    if output.exists():
+        state = json.loads(output.read_text(encoding="utf-8"))
+        if not isinstance(state, dict) or state.get("schemaVersion") != "maggie-generation.v1" or state.get("publish") is not False:
+            raise ValueError("invalid generation checkpoint")
+        if state.get("identity") != identity:
+            raise ValueError("source or generation contract changed; choose a new output")
+        translations = state.get("translations")
+        if not isinstance(translations, dict) or any(key not in {s["id"] for s in strings}
+                or not isinstance(value, str) or not value.strip() for key, value in translations.items()):
+            raise ValueError("invalid generation checkpoint")
+
+    def run(batch):
+        try:
+            result = adapter(batch, contract)
+            if isinstance(result, str):
+                result = json.loads(result)
+            if not isinstance(result, dict) or set(result) != {item["id"] for item in batch}:
+                raise ValueError("provider returned missing or unexpected IDs")
+            if any(not isinstance(value, str) or not value.strip() for value in result.values()):
+                raise ValueError("provider returned empty translations")
+        except (ValueError, json.JSONDecodeError):
+            if len(batch) == 1:
+                raise ValueError("provider output invalid for single source string") from None
+            midpoint = len(batch) // 2
+            run(batch[:midpoint])
+            run(batch[midpoint:])
+            return
+        state["translations"].update(result)
+        checkpoint(output, state)
+
+    pending = [item for item in strings if item["id"] not in state["translations"]]
+    state["status"] = "running"
+    checkpoint(output, state)
+    try:
+        batch, size = [], 0
+        for item in pending:
+            if batch and size + len(item["text"]) > character_budget:
+                run(batch)
+                batch, size = [], 0
+            batch.append(item)
+            size += len(item["text"])
+        if batch:
+            run(batch)
+    except Exception:
+        state["status"] = "failed"
+        checkpoint(output, state)
+        raise
+    state["status"] = "generated"
+    checkpoint(output, state)
+    return state

package/bundled-tools/runtime/maggie_blog.py

@@ -8,6 +8,8 @@ import re
 import shutil
 from datetime import datetime, timezone
 from pathlib import Path
+from localization_runner import checkpoint, generate
+from content_localization import valid_locale
 
 STATUSES = ("draft", "review", "approved", "published", "archived")
 DEFAULTS = {
@@ -20,6 +22,8 @@ DEFAULTS = {
     "pullIntervalMinutes": 120,
     "maxPerRun": 1,
     "fallbackImageMode": "gradient",
+    "autoTranslateEnabled": False,
+    "translationLocales": [],
 }
 
 
@@ -65,7 +69,62 @@ class BlogStore:
         return json.loads(self.posts_path.read_text(encoding="utf-8"))
 
     def _write(self, path: Path, value: object) -> None:
-        path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        checkpoint(path, value)
+
+    def reconcile_translations(self) -> list[dict]:
+        """Recover missing scheduling intents from persisted source, without re-pull."""
+        settings = self.settings()
+        if not settings.get("autoTranslateEnabled"):
+            return []
+        locales = settings.get("translationLocales", [])
+        if not isinstance(locales, list) or not locales or any(not isinstance(locale, str) or not valid_locale(locale) for locale in locales):
+            raise ValueError("auto translation requires supported translationLocales")
+        tasks = []
+        for post in self.posts():
+            for locale in sorted(set(locales)):
+                contract = {"projectId": post["projectId"], "contentId": post["contentId"],
+                            "sourceRevision": checksum({key: post[key] for key in
+                                ("title", "excerpt", "body", "topics", "source")}
+                                | {"images": post.get("images", [])}),
+                            "targetLocale": locale, "operation": "translate"}
+                identity = checksum(contract).split(":")[1]
+                path = self.root / "translations" / (identity + ".json")
+                if not path.exists():
+                    self._write(path, {"id": identity, "contract": contract, "status": "pending",
+                                      "attempts": 0, "isIndexable": False})
+                tasks.append(json.loads(path.read_text(encoding="utf-8")))
+        return tasks
+
+    def translate_pending(self, adapter, character_budget: int = 8000) -> dict:
+        """Single-worker draft translation; every caller uses reconciliation first."""
+        tasks = self.reconcile_translations()
+        posts = {post["contentId"]: post for post in self.posts()}
+        for task in tasks:
+            if task["status"] == "succeeded":
+                continue
+            post = posts[task["contract"]["contentId"]]
+            strings = [{"id": key, "text": text} for key, text in (
+                ("title", post["title"]), ("excerpt", post["excerpt"]),
+                ("body", post["body"].get("value", ""))) if isinstance(text, str) and text.strip()]
+            strings.extend({"id": "topic:" + str(index), "text": topic["label"]}
+                           for index, topic in enumerate(post["topics"]))
+            strings.extend({"id": "alt:" + str(index), "text": image["alt"]}
+                           for index, image in enumerate(post.get("images", []))
+                           if isinstance(image.get("alt"), str) and image["alt"].strip())
+            path = self.root / "translations" / (task["id"] + ".json")
+            task.update(status="running", attempts=task["attempts"] + 1)
+            self._write(path, task)
+            try:
+                result = generate(strings, task["contract"],
+                    self.root / "translations" / "checkpoints" / (task["id"] + ".json"),
+                    adapter, character_budget)
+                task.update(status="succeeded", draft=result["translations"], isIndexable=False)
+                task.pop("errorCategory", None)
+            except Exception as error:
+                task.update(status="failed", errorCategory=type(error).__name__)
+            self._write(path, task)
+        return {"status": "partial" if any(task["status"] != "succeeded" for task in tasks) else "completed",
+                "tasks": [{key: task[key] for key in ("id", "status", "attempts")} for task in tasks]}
 
     def _backup(self) -> None:
         if self.posts_path.exists():
@@ -91,6 +150,8 @@ class BlogStore:
                 "slug": old["slug"] if old else slugify(raw_slug),
                 "title": title,
                 "excerpt": str(item.get("excerpt") or ""),
+                "images": [{"src": image.get("src", ""), "alt": image.get("alt", "")}
+                           for image in item.get("images", []) if isinstance(image, dict)],
                 "body": item.get("body") if isinstance(item.get("body"), dict) else {"format": str(item.get("format") or "markdown"), "value": str(item.get("body") or item.get("content") or "")},
                 "topics": [{"slug": slugify(str(topic)), "label": str(topic)} for topic in item.get("topics", item.get("keywords", []))],
                 # Provider input can suggest a status, but cannot bypass the
@@ -111,8 +172,12 @@ class BlogStore:
         slugs = [post["slug"] for post in result]
         if len(slugs) != len(set(slugs)): raise ValueError("slug collision detected; provide unique slugs")
         self._backup(); self._write(self.posts_path, result)
+        translation_tasks = self.reconcile_translations()
         runs = json.loads(self.runs_path.read_text(encoding="utf-8")) if self.runs_path.exists() else []
         run = {"id": "pull:" + hashlib.sha256((now() + provider).encode()).hexdigest()[:12], "provider": provider, "status": "completed", "delivered": len(payload), "changed": changed, "finishedAt": now()}
+        run["translationTasks"] = len(translation_tasks)
+        if any(task["status"] != "succeeded" for task in translation_tasks):
+            run["status"] = "partial"
         runs.append(run); self._write(self.runs_path, runs)
         return run