@topy-ai/maggie 0.6.6 → 0.6.8

package/README.md

@@ -154,11 +154,33 @@ The canary report requires a screenshot and zero console errors, missing
 assets, and visual placeholders for every route. It records safe cache headers
 only and never stores response bodies, cookies, or credentials.
 
+### Localization and analytics release gates
+
+Extract real page strings before creating a localization job, then require a
+clean rendered report before approval:
+
+```bash
+maggie localization extract --project . --source-dir src \
+  --output .maggie/localization/source.json
+maggie localization plan --project . --content content.json \
+  --source .maggie/localization/source.json --source-lang en \
+  --target-lang zh-Hant --locale zh-Hant-TW --market global --operation translate
+maggie localization validate .maggie/localization/<job>.json \
+  --source .maggie/localization/source.json \
+  --render-report .maggie/localization/rendered.json
+```
+
+For analytics, the opt-in end-to-end gate combines the event contract,
+consent/network evidence, provider readback, browser rendering, referral
+redaction, and production smoke report. It fails closed on missing or unsafe
+evidence; see the repository analytics integration guide for the versioned
+artifact schemas.
+
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.6.6 update --project . --force
-npx @topy-ai/maggie@0.6.6 cleanup --project .
+npx @topy-ai/maggie@0.6.8 update --project . --force
+npx @topy-ai/maggie@0.6.8 cleanup --project .
 ```
 
 ## MaggieDash lifecycle

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.6.6 init --agent all
+npx @topy-ai/maggie@0.6.8 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 

package/bundled-skills/maggie-content-localization/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-content-localization
 description: Manage translation, polish, rewrite, market localization, review, stale detection, and publishing for pages, guides, posts, services, products, and categories.
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Maggie Content Localization
@@ -40,8 +40,16 @@ advisory and never bypasses validation or owner/Admin approval.
 python3 tools/clis/maggie_localization.py plan \
   --project . --content content.json --source-lang en --target-lang zh-Hans \
   --market uk --operation translate --locale zh-Hans-GB
+python3 tools/clis/maggie_localization.py extract --project . --source-dir src \
+  --routes-file docs/routes.tsv --output .maggie/localization/source.json
+python3 tools/clis/maggie_localization.py plan --project . --content content.json \
+  --source .maggie/localization/source.json --source-lang en --target-lang zh-Hans \
+  --market uk --operation translate --locale zh-Hans-GB
 python3 tools/clis/maggie_localization.py preview .maggie/localization/<job>.json
 python3 tools/clis/maggie_localization.py validate .maggie/localization/<job>.json
+python3 tools/clis/maggie_localization.py validate .maggie/localization/<job>.json \
+  --source .maggie/localization/source.json \
+  --render-report .maggie/localization/rendered.json
 python3 tools/clis/maggie_localization.py review .maggie/localization/<job>.json \
   --reviewer owner@example.com --decision approve
 python3 tools/clis/maggie_localization.py publish .maggie/localization/<job>.json --confirm
@@ -60,8 +68,11 @@ health claims, slug, canonical ownership, or content identity during a copy
 operation without structured approval. Incomplete or fallback output must be
 `isIndexable: false`. High-risk content requires Admin approval before publish.
 
-The current validator checks the localization record. It does not yet extract
-strings from a host project or prove browser-rendered language output. That
-larger capability is specified in
+The extractor is read-only and uses a conservative markup adapter for Astro,
+HTML, JSX/TSX, Vue, and Svelte. It records stable string IDs, source hashes,
+line numbers, routes, and attribute/text-node kinds while skipping scripts,
+styles, SVG, and dynamic expressions. Supplying source and render reports to
+`validate` makes the checks fail closed; the prepared `content.json` flow
+remains backward-compatible without those artifacts. See
 [`docs/localization-extraction-render-prd.md`](../../docs/localization-extraction-render-prd.md)
-and remains a separate release-gated feature.
+for the artifact contract and limitations.

package/bundled-skills/maggie-deployment/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Maggie Deployment
@@ -70,6 +70,20 @@ The output contains only the immutable release/current layout, systemd unit,
 Nginx reverse-proxy config, health commands and rollback command. It never
 contains credentials and never SSHs, changes DNS, restarts systemd or deploys.
 
+VPS plans include a bounded retention policy: keep two immutable releases,
+preserve the `current` target and rollback target, and review prune candidates
+before any operator executes cleanup. Generate a read-only candidate report:
+
+```bash
+python3 tools/clis/maggie_deployment.py --retention-plan \
+  --release-root /var/www/example \
+  --current-link /var/www/example/current \
+  --keep-releases 2 --output .maggie/deployment/retention-plan.json
+```
+
+The CLI never deletes release directories and never permits fewer than two
+retained releases.
+
 Validate the database release separately before a VPS migration:
 
 ```bash
@@ -81,6 +95,14 @@ The manifest must reference `DATABASE_URL` (not a literal URL), declare an
 advancing version, forward-only/idempotent policy, backup and restore commands,
 and a tested restore artifact. The validator never runs those commands.
 
+If a release depends on existing rows or seeded data, set
+`dataDependencies: true` in `.maggie/migration-manifest.json` and provide
+`.maggie/deployment/data-release.json` before deployment. The checkpoint must
+use `maggie-data-release.v1`, declare `requiredTables`, compare
+`previousCounts` and `currentCounts`, and include the release, check time, and
+`passed: true`. Deployment preflight fails closed when this evidence is absent
+or incomplete; it does not copy or mutate data.
+
 Validate and materialise scheduled jobs only after their quota and lock policy
 has been reviewed:
 

package/bundled-tools/clis/maggie_analytics.py

@@ -7,6 +7,7 @@ import argparse
 import json
 import os
 import re
+import subprocess
 from pathlib import Path
 from urllib.parse import urlsplit
 
@@ -14,6 +15,7 @@ from urllib.parse import urlsplit
 GA4_ID = re.compile(r"^G-[A-Z0-9]+$", re.I)
 ALLOWED_EVENTS = {"page_view", "blog_post_view", "booking_click"}
 FORBIDDEN_EVENTS = re.compile(r"(?:purchase|revenue|confirmed[_-]?booking|completed[_-]?treatment|transaction_id)", re.I)
+SENSITIVE_FIELDS = re.compile(r"(?:email|phone|name|address|ip|user[_-]?id|client[_-]?id|query|referrer)", re.I)
 
 
 def parse_env(path: Path) -> dict[str, str]:
@@ -33,13 +35,94 @@ def check(name: str, passed: bool, evidence: str, checks: dict) -> None:
     checks[name] = {"passed": bool(passed), "evidence": evidence}
 
 
+def load_json(path: Path, label: str) -> tuple[dict | None, list[str]]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return None, [f"{label}: {exc}"]
+    if not isinstance(value, dict):
+        return None, [f"{label}: JSON root must be an object"]
+    return value, []
+
+
+def release_gate(args: argparse.Namespace) -> int:
+    project = Path(args.project).resolve()
+    checks: dict[str, dict] = {}
+    errors: list[str] = []
+    contract, contract_errors = load_json(Path(args.contract).resolve(), "contract")
+    errors.extend(contract_errors)
+    if contract:
+        check("contract-schema", contract.get("schemaVersion") == "maggie-analytics-contract.v1", "versioned analytics contract", checks)
+        events = contract.get("events")
+        valid_events = isinstance(events, list) and bool(events) and all(isinstance(event, str) and re.fullmatch(r"[a-z][a-z0-9_]{1,63}", event) and not FORBIDDEN_EVENTS.search(event) for event in events)
+        check("event-contract", valid_events, "event names are lowercase, bounded, and do not claim revenue", checks)
+        destinations = contract.get("destinations")
+        check("destination-contract", isinstance(destinations, list) and bool(destinations) and all(isinstance(item, str) and item in {"ga4", "gtm", "gsc"} for item in destinations), "destinations are from the supported provider set", checks)
+        fields = contract.get("allowedParameters", [])
+        check("parameter-privacy", isinstance(fields, list) and all(isinstance(field, str) and not SENSITIVE_FIELDS.search(field) for field in fields), "allowed event parameters exclude identity and raw acquisition signals", checks)
+        if isinstance(contract.get("referralSources"), list):
+            check("referral-contract", set(contract["referralSources"]).issubset({"search", "partner", "social", "email", "direct", "unknown"}), "referral categories use the redacted taxonomy", checks)
+        else:
+            check("referral-contract", False, "contract must declare referralSources", checks)
+    browser, browser_errors = load_json(Path(args.render_report).resolve(), "render-report")
+    errors.extend(browser_errors)
+    network, network_errors = load_json(Path(args.network_report).resolve(), "network-report")
+    errors.extend(network_errors)
+    provider, provider_errors = load_json(Path(args.provider_report).resolve(), "provider-report")
+    errors.extend(provider_errors)
+    smoke, smoke_errors = load_json(Path(args.smoke_report).resolve(), "smoke-report")
+    errors.extend(smoke_errors)
+    if browser:
+        check("browser-schema", browser.get("schemaVersion") == "maggie-analytics-browser.v1", "versioned browser evidence", checks)
+        check("browser-render", browser.get("passed") is True and isinstance(browser.get("routes"), list) and bool(browser["routes"]), "routes rendered without a browser failure", checks)
+        check("browser-console", isinstance(browser.get("consoleErrors"), list) and not browser["consoleErrors"], "no browser console errors", checks)
+    if network:
+        pre = network.get("preConsentRequests")
+        check("pre-consent-network", isinstance(pre, list) and not pre, "no analytics requests before consent", checks)
+        check("network-redaction", network.get("redacted") is True, "network evidence is explicitly redacted", checks)
+        check("consented-network", isinstance(network.get("consentedRequests"), list), "consented network evidence is present", checks)
+    if provider:
+        check("provider-read-only", provider.get("schemaVersion") == "maggie-analytics-provider.v1" and provider.get("readOnly") is True and provider.get("authorized") is True and provider.get("passed") is True, "provider inspection is authorized, read-only, and passed", checks)
+    if smoke:
+        check("production-smoke", smoke.get("schemaVersion") == "maggie-analytics-smoke.v1" and smoke.get("passed") is True and bool(smoke.get("route")) and bool(smoke.get("release")) and bool(smoke.get("cache")), "public route, release, and cache smoke evidence", checks)
+    if contract and isinstance(contract.get("events"), list) and browser and isinstance(browser.get("consentedEvents"), list):
+        check("event-runtime-coverage", set(contract["events"]).issubset(set(browser["consentedEvents"])), "every contract event is present in consented browser evidence", checks)
+    failed = [name for name, item in checks.items() if not item["passed"]]
+    errors.extend(failed)
+    report = {
+        "schemaVersion": "maggie-analytics-release-gate.v1",
+        "environment": args.environment,
+        "project": str(project),
+        "checks": checks,
+        "passed": not errors,
+        "publish": False,
+        "mutation": "not executed",
+    }
+    output = project / ".maggie" / "analytics-release-gate.json"
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "passed" if report["passed"] else "failed", "environment": args.environment, "report": str(output), "failedChecks": failed, "publish": False}, indent=2))
+    return 0 if report["passed"] else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
+    parser.add_argument("command", nargs="?", choices=("release-gate",))
     parser.add_argument("--project", default=".")
     parser.add_argument("--environment", choices=("development", "staging", "production"), default="staging")
     parser.add_argument("--env-file", help="optional env file; values are never printed")
     parser.add_argument("--html", help="optional rendered HTML snapshot to inspect")
+    parser.add_argument("--contract", help="versioned analytics contract for release-gate")
+    parser.add_argument("--render-report", help="redacted browser/render evidence for release-gate")
+    parser.add_argument("--network-report", help="redacted network evidence for release-gate")
+    parser.add_argument("--provider-report", help="read-only provider evidence for release-gate")
+    parser.add_argument("--smoke-report", help="production smoke evidence for release-gate")
     args = parser.parse_args()
+    if args.command == "release-gate":
+        required = ("contract", "render_report", "network_report", "provider_report", "smoke_report")
+        if any(not getattr(args, name) for name in required):
+            parser.error("release-gate requires --contract, --render-report, --network-report, --provider-report, and --smoke-report")
+        return release_gate(args)
     project = Path(args.project).resolve()
     env = parse_env(Path(args.env_file).resolve()) if args.env_file else parse_env(project / ".env.example")
     env.update({key: value for key, value in os.environ.items() if key in {"PUBLIC_GA4_MEASUREMENT_ID", "PUBLIC_ANALYTICS_ENABLED", "PUBLIC_ANALYTICS_CONSENT_REQUIRED", "GSC_SITE_URL", "GSC_VERIFICATION_TOKEN"}})

package/bundled-tools/clis/maggie_deployment.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import json
 import re
+from datetime import datetime, timezone
 from pathlib import Path
 
 
@@ -57,10 +58,21 @@ def preflight(project: Path, target: str, environment: str) -> dict:
                 rollback_passed = bool(evidence.get("passed") is True and evidence.get("environment") == "production" and evidence.get("previousRelease") and evidence.get("testedAt"))
             except (OSError, json.JSONDecodeError):
                 rollback_passed = False
-        result["checks"].update({"node_runtime_declared": bool(package.get("engines", {}).get("node") or package.get("dependencies", {}).get("astro")), "start_command_or_runtime": "start" in scripts or "preview" in scripts, "stateless_or_migration_plan": True, "release_layout_declared": True, "rollback_command_declared": True, "remote_verification_pending": True, "release_plan_artifact": bool(plan_path and plan.get("release_layout") and plan.get("current_release")), "systemd_artifact": bool(systemd_text and "ExecStart=" in systemd_text and "EnvironmentFile=" in systemd_text and "NoNewPrivileges=true" in systemd_text), "nginx_artifact": bool(nginx_text and "proxy_pass" in nginx_text and "server_name" in nginx_text), "deployment_artifacts_secret_free": secret_free, "rollback_evidence": rollback_passed if environment == "production" else True})
+        migration_manifest = project / ".maggie" / "migration-manifest.json"
+        migration = {}
+        if migration_manifest.exists():
+            try:
+                migration = json.loads(migration_manifest.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                migration = {}
+        data_path = project / ".maggie" / "deployment" / "data-release.json"
+        data_required = bool(migration.get("dataDependencies"))
+        data_checkpoint = validate_data_checkpoint(data_path) if data_path.exists() else {"passed": not data_required, "declared": False, "errors": ["data-release.json is required for a data-dependent release"] if data_required else []}
+        retention_ok = bool(plan.get("retention", {}).get("keep") in (2, 3, 4, 5) and plan.get("retention", {}).get("prune") and plan.get("retention", {}).get("preserve"))
+        result["checks"].update({"node_runtime_declared": bool(package.get("engines", {}).get("node") or package.get("dependencies", {}).get("astro")), "start_command_or_runtime": "start" in scripts or "preview" in scripts, "stateless_or_migration_plan": True, "release_layout_declared": True, "rollback_command_declared": True, "release_retention_policy": retention_ok, "data_release_checkpoint": data_checkpoint["passed"], "remote_verification_pending": True, "release_plan_artifact": bool(plan_path and plan.get("release_layout") and plan.get("current_release")), "systemd_artifact": bool(systemd_text and "ExecStart=" in systemd_text and "EnvironmentFile=" in systemd_text and "NoNewPrivileges=true" in systemd_text), "nginx_artifact": bool(nginx_text and "proxy_pass" in nginx_text and "server_name" in nginx_text), "deployment_artifacts_secret_free": secret_free, "rollback_evidence": rollback_passed if environment == "production" else True})
         result["vps"] = {"runtime":"Node.js standalone","reverseProxy":"Nginx","processManager":"systemd","releaseLayout":"/var/www/<site>/releases/<release> + current symlink","dns":"Cloudflare DNS or registrar DNS; verify apex and www separately","remoteCommands":["npm ci","npm run build","systemctl restart <service>","systemctl is-active <service>","curl -fsS https://<domain>/robots.txt","curl -fsS https://<domain>/sitemap.xml"],"handoverFields":["host","sshUser","domain","service","release","previousRelease","nginxConfig","migrationVersion","verification","rollback"]}
         result["next_action"] = "review VPS host, SSH user, domain/DNS, systemd service, Nginx config, release path, migrations, and rollback owner before execute"
-        result["blocking_checks"] = ["package_manifest", "build_command", "env_example", "node_runtime_declared", "start_command_or_runtime", "stateless_or_migration_plan", "release_layout_declared", "rollback_command_declared", "release_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
+        result["blocking_checks"] = ["package_manifest", "build_command", "env_example", "node_runtime_declared", "start_command_or_runtime", "stateless_or_migration_plan", "release_layout_declared", "rollback_command_declared", "release_retention_policy", "data_release_checkpoint", "release_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
     else:
         result["blocking_checks"] = ["package_manifest", "build_command", "env_example"]
     return result
@@ -85,6 +97,7 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> di
         "current_release": current,
         "node_port": node_port,
         "release_layout": f"{root}/releases/<immutable-release> plus current symlink",
+        "retention": {"keep": 2, "preserve": [current, f"{root}/releases/<previous-release>"], "prune": f"find {root}/releases -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | tail -n +3 | cut -d' ' -f2- | xargs -r rm -rf --"},
         "staging_first": True,
         "secrets": "external environment file; no secrets in generated artifacts",
         "commands": {
@@ -101,6 +114,38 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> di
     }
 
 
+def validate_data_checkpoint(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"passed": False, "declared": True, "errors": [f"data checkpoint unreadable: {exc}"]}
+    required = value.get("requiredTables")
+    previous = value.get("previousCounts")
+    current = value.get("currentCounts")
+    errors = []
+    if value.get("schemaVersion") != "maggie-data-release.v1": errors.append("data checkpoint schemaVersion is unsupported")
+    if value.get("passed") is not True: errors.append("data checkpoint is not passed")
+    if not isinstance(required, list) or not required: errors.append("requiredTables must be a non-empty list")
+    if not isinstance(previous, dict) or not isinstance(current, dict): errors.append("previousCounts and currentCounts are required")
+    if isinstance(required, list) and isinstance(current, dict):
+        missing = [table for table in required if table not in current]
+        if missing: errors.append("currentCounts is missing required tables")
+    if not value.get("release") or not value.get("checkedAt"): errors.append("release and checkedAt are required")
+    return {"passed": not errors, "declared": True, "errors": errors}
+
+
+def retention_plan(release_root: str, current_link: str, keep: int) -> dict:
+    if keep < 2 or keep > 5:
+        raise ValueError("keep must be between 2 and 5")
+    root = Path(release_root).resolve()
+    releases = sorted((path for path in root.iterdir() if path.is_dir() and not path.is_symlink()), key=lambda path: path.stat().st_mtime, reverse=True) if root.is_dir() else []
+    current_target = Path(current_link).resolve() if Path(current_link).exists() else None
+    preserved = {str(current_target)} if current_target else set()
+    preserved.update(str(path) for path in releases[:keep])
+    candidates = [str(path) for path in releases if str(path) not in preserved]
+    return {"schemaVersion": "maggie-retention-plan.v1", "releaseRoot": str(root), "currentLink": str(Path(current_link)), "keep": keep, "preserved": sorted(preserved), "candidates": candidates, "mutation": "not executed", "generatedAt": datetime.now(timezone.utc).isoformat()}
+
+
 def write_vps_plan(output_dir: Path, plan: dict) -> None:
     output_dir.mkdir(parents=True, exist_ok=True)
     domain = plan["domain"]
@@ -158,6 +203,9 @@ def main() -> int:
     parser.add_argument("--release-root", default="/var/www/maggie-site", help="immutable release root")
     parser.add_argument("--node-port", type=int, default=4321)
     parser.add_argument("--plan-dir", help="directory for generated VPS artifacts")
+    parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
+    parser.add_argument("--current-link", help="current symlink for --retention-plan")
+    parser.add_argument("--keep-releases", type=int, default=2)
     args = parser.parse_args()
     try:
         if args.vps_plan:
@@ -168,6 +216,16 @@ def main() -> int:
                 write_vps_plan(Path(args.plan_dir).resolve(), plan)
             print(json.dumps(plan, indent=2, ensure_ascii=False))
             return 0
+        if args.retention_plan:
+            if not args.current_link:
+                parser.error("--current-link is required with --retention-plan")
+            plan = retention_plan(args.release_root, args.current_link, args.keep_releases)
+            output = Path(args.output).resolve() if args.output else None
+            if output:
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_text(json.dumps(plan, indent=2) + "\n", encoding="utf-8")
+            print(json.dumps(plan, indent=2, ensure_ascii=False))
+            return 0
         result = preflight(Path(args.project).resolve(), args.target, args.environment)
         if args.output:
             Path(args.output).parent.mkdir(parents=True, exist_ok=True)

package/bundled-tools/clis/maggie_localization.py

@@ -26,6 +26,133 @@ def load(path: Path) -> dict:
     return value
 
 
+MARKUP_EXTENSIONS = {".astro", ".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte"}
+SKIP_TAGS = re.compile(r"<(?:script|style|noscript|svg)\b[^>]*>.*?</(?:script|style|noscript|svg)\s*>", re.I | re.S)
+TAG_PATTERN = re.compile(r"<[^>]*>")
+ATTR_PATTERN = re.compile(r"\b(?:alt|title|aria-label|placeholder)\s*=\s*([\"'])(.*?)\1", re.I | re.S)
+
+
+def source_revision(files: list[Path], root: Path) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(files):
+        digest.update(str(path.relative_to(root)).encode("utf-8"))
+        digest.update(path.read_bytes())
+    return digest.hexdigest()[:16]
+
+
+def extract_file(path: Path, root: Path, route: str) -> list[dict]:
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    cleaned = SKIP_TAGS.sub("", raw)
+    strings: list[dict] = []
+    occupied: list[tuple[int, int]] = []
+
+    def add(value: str, start: int, kind: str) -> None:
+        value = re.sub(r"\s+", " ", value).strip()
+        if len(value) < 2 or "{" in value or "}" in value or re.fullmatch(r"[\W_]+", value or ""):
+            return
+        line = raw.count("\n", 0, start) + 1
+        relative = str(path.relative_to(root))
+        identity = f"{relative}:{line}:{kind}:{value}"
+        strings.append({
+            "id": "src-" + hashlib.sha256(identity.encode("utf-8")).hexdigest()[:16],
+            "file": relative,
+            "line": line,
+            "route": route,
+            "kind": kind,
+            "text": value,
+            "sourceHash": hashlib.sha256(value.encode("utf-8")).hexdigest()[:16],
+            "translatable": True,
+        })
+
+    for match in TAG_PATTERN.finditer(cleaned):
+        tag = match.group(0)
+        for attr in ATTR_PATTERN.finditer(tag):
+            offset = match.start() + attr.start(2)
+            add(attr.group(2), offset, "attribute")
+        occupied.append((match.start(), match.end()))
+    last = 0
+    for start, end in occupied:
+        if start > last:
+            add(cleaned[last:start], last, "text")
+        last = end
+    if last < len(cleaned):
+        add(cleaned[last:], last, "text")
+    return strings
+
+
+def extract_source(args: argparse.Namespace) -> int:
+    project = args.project.resolve()
+    source_dir = (project / args.source_dir).resolve()
+    if not source_dir.is_dir() or project not in source_dir.parents and source_dir != project:
+        raise ValueError("source-dir must be an existing directory inside project")
+    routes: dict[str, str] = {}
+    if args.routes_file:
+        route_path = (project / args.routes_file).resolve()
+        if route_path.exists():
+            for line in route_path.read_text(encoding="utf-8", errors="replace").splitlines():
+                parts = line.split("\t", 1)
+                if len(parts) == 2 and parts[0].strip() and parts[1].strip():
+                    routes[parts[0].strip()] = parts[1].strip()
+    files = [path for path in source_dir.rglob("*") if path.is_file() and path.suffix.lower() in MARKUP_EXTENSIONS]
+    strings: list[dict] = []
+    for path in sorted(files):
+        relative = str(path.relative_to(project))
+        strings.extend(extract_file(path, project, routes.get(relative, "unknown")))
+    revision = source_revision(files, project)
+    output = (project / args.output).resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    artifact = {
+        "schemaVersion": "maggie-localization-source.v1",
+        "sourceRevision": revision,
+        "sourceRoot": str(source_dir.relative_to(project)),
+        "files": [str(path.relative_to(project)) for path in files],
+        "strings": strings,
+        "extraction": {"adapter": "conservative-markup", "readOnly": True, "supportedExtensions": sorted(MARKUP_EXTENSIONS)},
+    }
+    output.write_text(json.dumps(artifact, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "passed", "output": str(output), "files": len(files), "strings": len(strings), "sourceRevision": revision}, indent=2))
+    return 0
+
+
+def validate_source(path: Path, expected_revision: str | None) -> list[str]:
+    source = load(path)
+    errors: list[str] = []
+    if source.get("schemaVersion") != "maggie-localization-source.v1":
+        errors.append("source artifact schemaVersion is unsupported")
+    strings = source.get("strings")
+    if not isinstance(strings, list) or not strings:
+        errors.append("source artifact has no extracted strings")
+    seen: set[str] = set()
+    for item in strings if isinstance(strings, list) else []:
+        if not isinstance(item, dict) or not item.get("id") or item.get("id") in seen:
+            errors.append("source strings must have unique IDs")
+            continue
+        seen.add(item["id"])
+        if any(marker in str(item.get("text", "")) for marker in ("{", "}")):
+            errors.append(f"source string contains an expression: {item.get('id')}")
+        if not item.get("file") or not item.get("line") or not item.get("sourceHash"):
+            errors.append(f"source string metadata is incomplete: {item.get('id')}")
+    if expected_revision and source.get("sourceRevision") != expected_revision:
+        errors.append("source revision does not match localization job")
+    return errors
+
+
+def validate_render_report(path: Path) -> list[str]:
+    report = load(path)
+    errors: list[str] = []
+    if report.get("schemaVersion") != "maggie-localization-render.v1":
+        errors.append("render report schemaVersion is unsupported")
+    if report.get("passed") is not True:
+        errors.append("render report is not passed")
+    for field in ("routes", "consoleErrors", "failedAssets", "untranslatedRequired"):
+        if field not in report:
+            errors.append(f"render report is missing {field}")
+    for field in ("consoleErrors", "failedAssets", "untranslatedRequired"):
+        if isinstance(report.get(field), list) and report[field]:
+            errors.append(f"render report has {field}")
+    return errors
+
+
 def safe_job_content_token(content_id: str) -> str:
     """Make a content identity safe for a single filename component."""
     token = re.sub(r"[^A-Za-z0-9._-]+", "-", str(content_id)).strip(".-_") or "content"
@@ -36,6 +163,7 @@ def safe_job_content_token(content_id: str) -> str:
 
 def plan_job(args: argparse.Namespace) -> int:
     content = load(args.content)
+    source_artifact = load(args.source) if getattr(args, "source", None) else None
     if args.source_lang not in LANGUAGES or args.target_lang not in LANGUAGES:
         raise ValueError("source-lang and target-lang must be in the supported language registry")
     if args.market not in MARKETS:
@@ -59,11 +187,18 @@ def plan_job(args: argparse.Namespace) -> int:
         "targetLocale": args.locale,
         "operation": args.operation,
         "translationGroupId": identity.get("translationGroupId", f"tg-{content_id}"),
-        "sourceRevision": args.source_revision or content.get("sourceRevision", "unknown"),
+        "sourceRevision": args.source_revision or (source_artifact or {}).get("sourceRevision") or content.get("sourceRevision", "unknown"),
         "status": "draft",
         "translation": {"translationStatus": "draft", "isIndexable": False},
         "createdAt": now(),
     }
+    if source_artifact:
+        if source_artifact.get("schemaVersion") != "maggie-localization-source.v1":
+            raise ValueError("source artifact schemaVersion is unsupported")
+        source_strings = source_artifact.get("strings", [])
+        if not isinstance(source_strings, list) or not source_strings:
+            raise ValueError("source artifact has no extracted strings")
+        job["translation"]["sourceStringIds"] = [item.get("id") for item in source_strings if isinstance(item, dict) and item.get("id")]
     output = Path(args.project) / ".maggie" / "localization" / f"{job['jobId']}.json"
     output.parent.mkdir(parents=True, exist_ok=True)
     output.write_text(json.dumps(job, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
@@ -71,7 +206,7 @@ def plan_job(args: argparse.Namespace) -> int:
     return 0
 
 
-def validate_job(path: Path) -> dict:
+def validate_job(path: Path, source_path: Path | None = None, render_path: Path | None = None) -> dict:
     job = load(path)
     errors = []
     if job.get("operation") not in OPERATIONS:
@@ -93,6 +228,15 @@ def validate_job(path: Path) -> dict:
         })
     }, expected_lang=job.get("targetLanguage")))
     errors.extend(f"protected field changed without approval: {field}" for field in protected_field_changes(job.get("content", {}), translation))
+    if source_path:
+        errors.extend(validate_source(source_path, job.get("sourceRevision")))
+        source = load(source_path)
+        source_ids = {item.get("id") for item in source.get("strings", []) if isinstance(item, dict)}
+        linked_ids = translation.get("sourceStringIds")
+        if not isinstance(linked_ids, list) or set(linked_ids) != source_ids:
+            errors.append("translation sourceStringIds must link every extracted source string")
+    if render_path:
+        errors.extend(validate_render_report(render_path))
     return {"passed": not errors, "errors": errors, "jobId": job.get("jobId"), "status": job.get("status")}
 
 
@@ -172,8 +316,17 @@ def main() -> int:
     plan_parser.add_argument("--market", required=True)
     plan_parser.add_argument("--operation", required=True)
     plan_parser.add_argument("--source-revision")
-    for name in ("preview", "validate"):
-        sub.add_parser(name).add_argument("job", type=Path)
+    plan_parser.add_argument("--source", type=Path, help="optional extracted source artifact")
+    sub.add_parser("preview").add_argument("job", type=Path)
+    validate_parser = sub.add_parser("validate")
+    validate_parser.add_argument("job", type=Path)
+    validate_parser.add_argument("--source", type=Path)
+    validate_parser.add_argument("--render-report", type=Path)
+    extract_parser = sub.add_parser("extract")
+    extract_parser.add_argument("--project", type=Path, default=Path("."))
+    extract_parser.add_argument("--source-dir", default="src")
+    extract_parser.add_argument("--routes-file")
+    extract_parser.add_argument("--output", default=".maggie/localization/source.json")
     review_parser = sub.add_parser("review")
     review_parser.add_argument("job", type=Path); review_parser.add_argument("--reviewer", required=True); review_parser.add_argument("--decision", required=True)
     publish_parser = sub.add_parser("publish")
@@ -185,7 +338,8 @@ def main() -> int:
         if args.command == "plan": return plan_job(args)
         if args.command == "preview": return preview(args.job)
         if args.command == "validate":
-            result = validate_job(args.job); print(json.dumps(result, indent=2)); return 0 if result["passed"] else 1
+            result = validate_job(args.job, args.source, args.render_report); print(json.dumps(result, indent=2)); return 0 if result["passed"] else 1
+        if args.command == "extract": return extract_source(args)
         if args.command == "review": return review(args.job, args.reviewer, args.decision)
         if args.command == "publish": return publish(args.job, args.confirm)
         if args.command == "stale": return stale_jobs(args.project)

package/bundled-tools/clis/maggie_release.py

@@ -212,6 +212,12 @@ def main() -> int:
     parser.add_argument("--output", help="release evidence JSON path")
     parser.add_argument("--skip-compatibility", action="store_true", help="skip the optional schema rehearsal; not recommended for release")
     parser.add_argument("--base-url", help="optional live/staging URL for homepage, admin redirect and 404 smoke")
+    parser.add_argument("--analytics-release-gate", action="store_true", help="require the end-to-end analytics evidence gate")
+    parser.add_argument("--analytics-contract")
+    parser.add_argument("--analytics-render-report")
+    parser.add_argument("--analytics-network-report")
+    parser.add_argument("--analytics-provider-report")
+    parser.add_argument("--analytics-smoke-report")
     args = parser.parse_args()
     project = Path(args.project).resolve()
     if not project.is_dir():
@@ -221,6 +227,21 @@ def main() -> int:
     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))
+    if args.analytics_release_gate:
+        evidence = {
+            "--contract": args.analytics_contract,
+            "--render-report": args.analytics_render_report,
+            "--network-report": args.analytics_network_report,
+            "--provider-report": args.analytics_provider_report,
+            "--smoke-report": args.analytics_smoke_report,
+        }
+        missing = [name for name, value in evidence.items() if not value]
+        if missing:
+            parser.error("--analytics-release-gate requires " + ", ".join(missing))
+        analytics_command = [sys.executable, str(ROOT / "maggie_analytics.py"), "release-gate", "--project", str(project), "--environment", args.environment]
+        for name, value in evidence.items():
+            analytics_command.extend([name, value])
+        gates.append(run_gate("analytics-release-gate", analytics_command, project))
     gates.append(editorial_gate(project))
     gates.append(evidence_gate(project, args.environment))
     if args.base_url:

package/bundled-tools/integrations/analytics.md

@@ -46,3 +46,29 @@ Use `--environment production` during release preflight. It fails closed until
 GA4 is explicitly enabled with a valid measurement ID and `GSC_SITE_URL` is
 configured. The CLI never prints secret values and does not claim confirmed
 bookings or revenue from outbound booking clicks.
+
+## End-to-end release gate
+
+For a release that has browser and provider evidence, use the opt-in gate:
+
+```bash
+maggie analytics release-gate --project . --environment staging \
+  --contract .maggie/analytics-contract.json \
+  --render-report .maggie/analytics-browser.json \
+  --network-report .maggie/analytics-network.json \
+  --provider-report .maggie/analytics-provider.json \
+  --smoke-report .maggie/analytics-smoke.json
+```
+
+The contract must use `maggie-analytics-contract.v1` and declare event names,
+supported destinations, privacy-safe parameters, and the redacted referral
+taxonomy. Evidence uses versioned schemas: browser
+`maggie-analytics-browser.v1`, network `maggie-analytics-network.v1`, provider
+`maggie-analytics-provider.v1`, and smoke `maggie-analytics-smoke.v1`.
+Pre-consent requests must be empty; provider evidence must be read-only and
+authorized; rendered routes, cache/release smoke, and all contract events must
+pass. Reports contain metadata only and never raw URLs, query strings, request
+bodies, credentials, or identity fields.
+
+To include it in the aggregate release preflight, pass the same five files to
+`maggie release` with `--analytics-release-gate`.

package/package.json

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