@topy-ai/maggie 0.1.0

package/bundled-tools/clis/maggie.py

@@ -0,0 +1,748 @@
+#!/usr/bin/env python3
+"""Maggie's dependency-free project analysis and bootstrap gate CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+
+STATE_DIR = ".maggie"
+STATE_FILE = "bootstrap-state.json"
+IGNORED_DIRS = {".git", ".next", "node_modules", "dist", "build", "coverage", "generated"}
+TEXT_SUFFIXES = {".css", ".html", ".js", ".jsx", ".md", ".mdx", ".svelte", ".ts", ".tsx", ".vue", ".astro", ".njk", ".liquid", ".json", ".yaml", ".yml"}
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def files_for(root: Path):
+    for path in root.rglob("*"):
+        if not path.is_file() or any(part in IGNORED_DIRS for part in path.parts):
+            continue
+        if path.name.startswith(".") and path.name not in {".env.example"}:
+            continue
+        yield path
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return ""
+
+
+def evidence(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def package_info(root: Path) -> tuple[dict, Path | None]:
+    candidates = [root / "package.json"] + sorted(path for path in root.glob("*/package.json") if path.parent.name not in IGNORED_DIRS)
+    parsed: list[tuple[int, dict, Path]] = []
+    for package in candidates:
+        if not package.exists():
+            continue
+        try:
+            value = json.loads(package.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        deps = dependency_names(value)
+        scripts = value.get("scripts") or {}
+        score = (10 if deps & {"astro", "next", "@sveltejs/kit", "nuxt", "@11ty/eleventy"} else 0) + (3 if "build" in scripts else 0) + (2 if "dev" in scripts else 0)
+        parsed.append((score, value, package))
+    if not parsed:
+        return {}, None
+    _, value, package = max(parsed, key=lambda item: (item[0], -len(item[2].parts)))
+    return value, package
+
+
+def dependency_names(package: dict) -> set[str]:
+    return set((package.get("dependencies") or {})) | set((package.get("devDependencies") or {}))
+
+
+def detect(root: Path) -> dict:
+    package, package_path = package_info(root)
+    deps = dependency_names(package)
+    scripts = package.get("scripts") or {}
+    all_files = list(files_for(root))
+    names = {path.name for path in all_files}
+    rel_paths = [evidence(path, root) for path in all_files]
+
+    def found(value: str, source: str) -> dict:
+        return {"status": "Detected", "value": value, "evidence": [source]}
+
+    def missing(value: str = "not found") -> dict:
+        return {"status": "Missing", "value": value, "evidence": []}
+
+    if "astro" in deps or any(path.endswith(".astro") for path in rel_paths):
+        framework = found("astro", "package.json" if "astro" in deps else next(path for path in rel_paths if path.endswith(".astro")))
+    elif "next" in deps or any(path.startswith("app/") or path.startswith("pages/") for path in rel_paths):
+        framework = found("next", "package.json" if "next" in deps else "app/ or pages/")
+    elif "@sveltejs/kit" in deps:
+        framework = found("sveltekit", "package.json")
+    elif "nuxt" in deps:
+        framework = found("nuxt", "package.json")
+    elif "@11ty/eleventy" in deps or any(name == ".eleventy.js" for name in names):
+        framework = found("eleventy", "package.json" if "@11ty/eleventy" in deps else ".eleventy.js")
+    else:
+        framework = {"status": "Unknown", "value": "no supported framework detected", "evidence": []}
+
+    ts_files = [path for path in rel_paths if Path(path).suffix in {".ts", ".tsx"}]
+    js_files = [path for path in rel_paths if Path(path).suffix in {".js", ".jsx"}]
+    if ts_files:
+        language = found("typescript", ts_files[0])
+    elif js_files:
+        language = found("javascript", js_files[0])
+    else:
+        language = {"status": "Unknown", "value": "no TypeScript or JavaScript source detected", "evidence": []}
+
+    lockfiles = {"pnpm-lock.yaml": "pnpm", "yarn.lock": "yarn", "bun.lockb": "bun", "package-lock.json": "npm"}
+    package_manager = next((found(manager, lockfile) for lockfile, manager in lockfiles.items() if lockfile in names), {"status": "Unknown", "value": "not detected", "evidence": []})
+
+    ui_candidates = {"tailwindcss": "tailwind", "@mui/material": "mui", "@chakra-ui/react": "chakra", "styled-components": "styled-components", "@radix-ui/react": "radix"}
+    ui = next((found(value, "package.json") for dep, value in ui_candidates.items() if dep in deps), None)
+    if not ui:
+        css_evidence = next((path for path in rel_paths if Path(path).suffix == ".css"), None)
+        ui = found("plain-css-or-custom", css_evidence) if css_evidence else {"status": "Unknown", "value": "no UI system detected", "evidence": []}
+
+    icon_candidates = {"@heroicons/react": "heroicons", "lucide-react": "lucide", "@fortawesome/fontawesome": "fontawesome", "react-icons": "react-icons"}
+    icons = next((found(value, "package.json") for dep, value in icon_candidates.items() if dep in deps), {"status": "Unknown", "value": "no icon set detected", "evidence": []})
+
+    font_path = next((path for path in rel_paths if Path(path).suffix in {".woff", ".woff2", ".ttf", ".otf"}), None)
+    font_css = next((path for path in rel_paths if Path(path).suffix == ".css" and "@font-face" in read_text(root / path)), None)
+    typography = found("local-font", font_path or font_css) if font_path or font_css else {"status": "Unknown", "value": "no custom font detected", "evidence": []}
+
+    db_candidates = {"prisma": "prisma", "drizzle-orm": "drizzle", "@libsql/client": "sqlite/libsql", "better-sqlite3": "sqlite", "pg": "postgresql", "mysql2": "mysql"}
+    database = next((found(value, "package.json") for dep, value in db_candidates.items() if dep in deps), None)
+    db_path = next((path for path in rel_paths if any(token in path.lower() for token in {"prisma", "drizzle", "migration", "schema.sql", "database"})), None)
+    if not database and db_path:
+        database = found("database-files-present", db_path)
+    if not database:
+        database = {"status": "Unknown", "value": "database engine and schema not detected", "evidence": []}
+
+    content_candidates = [path for path in rel_paths if Path(path).suffix in {".md", ".mdx", ".json"} and any(token in path.lower() for token in {"post", "blog", "content", "article"})]
+    if content_candidates:
+        content_source = found("local-content", content_candidates[0])
+    elif any(token in deps for token in {"contentlayer", "@content-collections/core"}):
+        content_source = found("content-library", "package.json")
+    else:
+        content_source = {"status": "Unknown", "value": "content source not detected", "evidence": []}
+
+    texts = "\n".join(read_text(path) for path in all_files if path.suffix in TEXT_SUFFIXES)
+    cjk = len(re.findall(r"[\u3400-\u9fff]", texts))
+    latin = len(re.findall(r"[A-Za-z]", texts))
+    if cjk > max(50, latin // 5):
+        content_language = {"status": "Likely", "value": "zh-or-multilingual", "evidence": ["text scan; confirm Traditional vs Simplified Chinese"]}
+    elif latin > 50:
+        content_language = {"status": "Likely", "value": "en-or-multilingual", "evidence": ["text scan; confirm locale"]}
+    else:
+        content_language = {"status": "Unknown", "value": "content language not detected", "evidence": []}
+
+    route_candidates = [path for path in rel_paths if any(token in path.lower() for token in {"sitemap", "robots", "post"})]
+    seo = {"status": "Detected" if route_candidates else "Missing", "value": "SEO/content route files found" if route_candidates else "blog/SEO route files not found", "evidence": route_candidates[:8]}
+
+    deployment_candidates = {"vercel.json": "vercel", "netlify.toml": "netlify", "fly.toml": "fly.io", "docker-compose.yml": "docker", "Dockerfile": "docker"}
+    deployment = next((found(value, filename) for filename, value in deployment_candidates.items() if filename in names), {"status": "Unknown", "value": "deployment platform not detected; confirm before changes", "evidence": []})
+    cms_candidates = {"wordpress": "wordpress", "@sanity/client": "sanity", "contentful": "contentful", "@strapi/strapi": "strapi", "payload": "payload"}
+    existing_cms = next((found(value, "package.json") for dep, value in cms_candidates.items() if dep in deps), {"status": "Unknown", "value": "no CMS detected", "evidence": []})
+    env_file = root / ".env.example"
+    environment = sorted(set(re.findall(r"^([A-Z][A-Z0-9_]+)=", read_text(env_file), re.MULTILINE)))
+    implementation_paths = [path for path in rel_paths if not any(part.lower() in {"docs", "documentation", "references"} for part in Path(path).parts) and Path(path).name.lower() not in {"readme.md", "changelog.md"}]
+    existing_routes = [path for path in implementation_paths if any(token in path.lower() for token in {"route", "page", "sitemap", "robots"})][:100]
+    route_inventory = {
+        "public": sorted(path for path in existing_routes if not any(token in path.lower() for token in {"api/", "ops", "admin", "dashboard"})),
+        "private_or_api": sorted(path for path in existing_routes if any(token in path.lower() for token in {"api/", "ops", "admin", "dashboard"})),
+        "evidence": existing_routes,
+    }
+    command_names = ("dev", "build", "test", "lint", "typecheck", "deploy")
+    validation_commands = {name: {"status": "Detected", "value": scripts[name], "evidence": ["package.json#scripts"]} if name in scripts else {"status": "Missing", "value": "not found", "evidence": []} for name in command_names}
+    runtime_candidates = {"@astrojs/node": "node-server", "@astrojs/cloudflare": "cloudflare", "@opennextjs/cloudflare": "cloudflare", "wrangler": "cloudflare", "vercel": "vercel", "netlify-cli": "netlify"}
+    runtime = next((found(value, "package.json") for dep, value in runtime_candidates.items() if dep in deps), {"status": "Unknown", "value": "runtime/adapter not detected", "evidence": []})
+    asset_contract = {
+        "redirects": found("present", "redirects file") if any(name in names for name in {"_redirects", "redirects.json", "redirects.csv"}) else missing("no redirects manifest detected"),
+        "security_headers": found("present", name) if (name := next((name for name in {"_headers", "headers.json", "vercel.json", "netlify.toml"} if name in names), None)) else missing("no deployment/header policy detected"),
+        "favicon_or_brand": found("present", path) if (path := next((path for path in implementation_paths if any(token in path.lower() for token in {"favicon", "logo", "brand"}) and Path(path).suffix in {".svg", ".png", ".ico", ".webp"}), None)) else missing("no favicon or brand asset detected"),
+        "social_image": found("present", path) if (path := next((path for path in implementation_paths if any(token in path.lower() for token in {"og", "social", "twitter"}) and Path(path).suffix in {".jpg", ".jpeg", ".png", ".webp"}), None)) else missing("no social image asset detected"),
+    }
+    content_model = {
+        "frontmatter": found("detected", path) if (path := next((path for path in implementation_paths if Path(path).suffix in {".md", ".mdx", ".astro"} and ("frontmatter" in read_text(root / path).lower() or re.search(r"^---\\s*$", read_text(root / path), re.MULTILINE))), None)) else missing("frontmatter contract not detected"),
+        "slug_field": found("detected", path) if (path := next((path for path in implementation_paths if "slug" in read_text(root / path).lower() and Path(path).suffix in TEXT_SUFFIXES), None)) else missing("slug field not detected"),
+        "last_modified": found("detected", path) if (path := next((path for path in implementation_paths if any(token in read_text(root / path).lower() for token in {"lastmod", "dateupdated", "datemodified", "updated_at"})), None)) else missing("last-modified contract not detected"),
+    }
+    risks = []
+    if framework["status"] in {"Unknown", "Missing"}: risks.append("framework must be confirmed before generator changes")
+    if database["status"] != "Detected": risks.append("database/schema is not detected; do not invent a persistence layer")
+    if existing_cms["status"] == "Detected": risks.append("existing CMS requires an explicit migration/source-of-truth decision")
+    if validation_commands["build"]["status"] != "Detected": risks.append("build command is not detected; establish a reproducible build gate before editing")
+    if not route_inventory["public"]: risks.append("public route inventory is empty; inspect the running app before generating blog routes")
+
+    return {
+        "schema_version": "1.1",
+        "analyzed_at": utc_now(),
+        "project_root": str(root),
+        "framework": framework,
+        "programming_language": language,
+        "package_manager": package_manager,
+        "content_language": content_language,
+        "ui_system": ui,
+        "icon_set": icons,
+        "typography": typography,
+        "database": database,
+        "content_source": content_source,
+        "seo_routes": seo,
+        "deployment": deployment,
+        "existing_cms": existing_cms,
+        "environment_variables": environment,
+        "existing_routes": existing_routes,
+        "route_inventory": route_inventory,
+        "runtime": runtime,
+        "validation_commands": validation_commands,
+        "asset_contract": asset_contract,
+        "content_model": content_model,
+        "recommended_architecture": {"status": "Needs confirmation", "value": "preserve detected framework/UI/database; add typed server-side blog adapter and explicit Ops boundary", "evidence": []},
+        "risks": risks,
+        "required_confirmations": ["framework", "language", "ui_system", "icon_set", "font", "database", "content_source", "deployment", "seo_routes"],
+        "planned_changes": ["typed post contract", "public blog routes", "sitemap/robots", "server-only integrations", "authenticated Ops routes"],
+        "package_json": evidence(package_path, root) if package_path else None,
+    }
+
+
+def state_path(root: Path) -> Path:
+    return root / STATE_DIR / STATE_FILE
+
+
+def load_state(root: Path) -> dict | None:
+    path = state_path(root)
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def require_bootstrap(root: Path) -> dict:
+    state = load_state(root)
+    if not state or state.get("status") != "completed":
+        print("BOOTSTRAP_REQUIRED: run `maggie bootstrap complete` after user confirmation.", file=sys.stderr)
+        raise SystemExit(2)
+    return state
+
+
+class ApiClient:
+    """Small API client with bounded retries and no secret-bearing output."""
+
+    def __init__(self, base_url: str, api_key: str, timeout: int = 30) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def request(self, method: str, path: str, body: dict | None = None, idempotency_key: str | None = None) -> object:
+        payload = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": "Maggie-CLI/0.1",
+        }
+        if payload is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        for attempt in range(3):
+            try:
+                request = Request(self.base_url + path, data=payload, headers=headers, method=method)
+                with urlopen(request, timeout=self.timeout) as response:
+                    raw = response.read(5_000_000).decode("utf-8", "replace")
+                    return json.loads(raw) if raw else {}
+            except HTTPError as error:
+                detail = error.read(2_000).decode("utf-8", "replace")
+                if error.code in {408, 429, 500, 502, 503, 504} and attempt < 2:
+                    time.sleep(2**attempt)
+                    continue
+                raise RuntimeError(f"Maggie API request failed ({error.code}): {detail}") from error
+            except URLError as error:
+                if attempt < 2:
+                    time.sleep(2**attempt)
+                    continue
+                raise RuntimeError(f"Maggie API request failed: {error.reason}") from error
+        raise RuntimeError("Maggie API request failed after retries")
+
+
+def api_client(args: argparse.Namespace) -> ApiClient:
+    api_key = os.getenv("AI_CMO_API_KEY")
+    if not api_key:
+        raise RuntimeError("set AI_CMO_API_KEY; the CLI never accepts API keys as positional arguments")
+    return ApiClient(getattr(args, "base_url", None) or os.getenv("AI_CMO_BASE_URL", "https://api.cmo.so"), api_key, getattr(args, "timeout", 30))
+
+
+def load_body(path: str) -> dict:
+    try:
+        body = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise RuntimeError(f"invalid JSON body file: {path}") from error
+    if not isinstance(body, dict):
+        raise RuntimeError("API request body must be a JSON object")
+    return body
+
+
+def print_api(value: object) -> None:
+    print(json.dumps(value, indent=2, ensure_ascii=False))
+
+
+def emit_api(value: object, args: argparse.Namespace) -> None:
+    serialized = json.dumps(value, indent=2, ensure_ascii=False) + "\n"
+    output = getattr(args, "output", None)
+    if output:
+        destination = Path(output)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        temporary = destination.with_name(destination.name + ".tmp")
+        with temporary.open("w", encoding="utf-8") as handle:
+            handle.write(serialized)
+            handle.flush()
+            os.fsync(handle.fileno())
+        temporary.replace(destination)
+        print(f"Saved API response to {destination}")
+    else:
+        print(serialized, end="")
+
+
+def require_execute(args: argparse.Namespace, root: Path | None = None) -> None:
+    if not args.execute:
+        print("DRY_RUN: no external request sent; add --execute to continue.")
+        return
+    if root is not None:
+        require_bootstrap(root)
+
+
+def command_api_get(args: argparse.Namespace) -> int:
+    path = args.path
+    if args.charges_quota and not getattr(args, "execute", False):
+        print("DRY_RUN: this delivery request can consume quota; add --execute to continue.")
+        return 0
+    if args.charges_quota and getattr(args, "execute", False) and not getattr(args, "output", None):
+        print("OUTPUT_REQUIRED: quota-consuming delivery requires --output so the response is persisted.", file=sys.stderr)
+        return 2
+    if args.charges_quota and getattr(args, "requires_bootstrap", False):
+        require_bootstrap(Path(args.project).resolve())
+    client = api_client(args)
+    emit_api(client.request("GET", path), args)
+    return 0
+
+
+def command_api_post(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve() if getattr(args, "project", None) else None
+    if not args.execute:
+        print("DRY_RUN: no external request sent; add --execute to continue.")
+        return 0
+    if getattr(args, "requires_bootstrap", False):
+        require_bootstrap(root)
+    body = load_body(args.body_file) if getattr(args, "body_file", None) else None
+    if getattr(args, "sitemap_url", None):
+        body = {"sitemap_url": args.sitemap_url}
+    key = getattr(args, "idempotency_key", None) or f"maggie-{args.path.strip('/').replace('/', '-')}-{int(time.time())}"
+    emit_api(api_client(args).request("POST", args.path, body, key), args)
+    return 0
+
+
+def command_rewrite_history(args: argparse.Namespace) -> int:
+    args.path = "/rewrite/history/" + quote(args.content_id, safe="")
+    args.charges_quota = False
+    return command_api_get(args)
+
+
+def command_analyze(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve()
+    result = detect(root)
+    if args.save:
+        output = root / STATE_DIR / "analysis.json"
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps(result, indent=2, ensure_ascii=False) if args.json else format_analysis(result))
+    return 0
+
+
+def format_analysis(result: dict) -> str:
+    lines = ["Maggie codebase analysis", f"Project: {result['project_root']}"]
+    for key in ("framework", "programming_language", "package_manager", "content_language", "ui_system", "icon_set", "typography", "database", "content_source", "existing_cms", "deployment", "runtime", "seo_routes"):
+        item = result[key]
+        lines.append(f"- {key}: [{item['status']}] {item['value']}" + (f" ({', '.join(item['evidence'])})" if item["evidence"] else ""))
+    commands = result.get("validation_commands", {})
+    if commands:
+        lines.append("- validation_commands: " + ", ".join(f"{name}={item['value']}" for name, item in commands.items() if item["status"] == "Detected"))
+    inventory = result.get("route_inventory", {})
+    lines.append(f"- route_inventory: {len(inventory.get('public', []))} public, {len(inventory.get('private_or_api', []))} private/API")
+    return "\n".join(lines)
+
+
+def command_status(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve()
+    state = load_state(root)
+    if not state:
+        print(json.dumps({"status": "not_started", "project_root": str(root)}, indent=2))
+        return 1
+    print(json.dumps(state, indent=2, ensure_ascii=False))
+    return 0 if state.get("status") == "completed" else 1
+
+
+def command_complete(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve()
+    required = {"foundation", "experience", "data", "publishing"}
+    confirmed = set(args.confirm or [])
+    missing = required - confirmed
+    if missing:
+        print("Confirmation required for: " + ", ".join(sorted(missing)), file=sys.stderr)
+        return 2
+    state = {
+        "schema_version": "1.0",
+        "status": "completed",
+        "completed_at": utc_now(),
+        "confirmed": {name: True for name in sorted(required)},
+        "decisions": {
+            "framework": args.framework,
+            "programming_language": args.language,
+            "content_language": args.content_language,
+            "ui_system": args.ui_system,
+            "icon_set": args.icon_set,
+            "font": args.font,
+            "database": args.database,
+            "content_source": args.content_source,
+        },
+    }
+    path = state_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    contracts = {
+        "project.json": {"schema_version": "1.0", "framework": args.framework, "language": args.language, "database": args.database, "content_source": args.content_source},
+        "decisions.json": state["decisions"],
+        "schema.json": {"post_required": ["id", "slug", "title", "content", "status", "canonicalUrl", "publishedAt", "updatedAt", "author"], "public_status": "published"},
+        "routes.json": {"public": ["/about", "/blog", "/blog/[slug]", "/topics", "/authors/[slug]", "/sitemap.xml", "/robots.txt"], "ops": ["/ops", "/ops/posts", "/ops/operations", "/ops/wordpress", "/api/ops/bulk", "/api/ops/agency", "/api/ops/entities", "/api/ops/migrations/[id]/resume", "/api/ops/wordpress/migration-plan", "/api/ops/pull/project-context", "/api/ops/pull/sync-updates", "/api/ops/sitemap/matching-history", "/api/ops/content-tracking/report-state", "/api/ops/content-tracking/report-state/batch", "/api/ops/playbooks/[id]/run"]},
+        "integrations.json": {"ai_cmo": "server-only", "gsc": "server-only", "ga4": "consent-aware"},
+        "migration.json": {"supported": ["wordpress-rest", "wxr", "csv", "json", "sitemap", "media-archive"], "idempotency": "source-id-and-checksum", "default_conflict": "manual", "sync_modes": ["all", "new", "modified"], "deleted_policy": "archive"},
+    }
+    for filename, content in contracts.items():
+        (path.parent / filename).write_text(json.dumps(content, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(f"Bootstrap completed: {path}")
+    return 0
+
+
+def command_generate(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve()
+    require_bootstrap(root)
+    if args.target == "contract":
+        print(f"Bootstrap contract already generated at {root / STATE_DIR}")
+        return 0
+    if args.target == "fixture":
+        output = root / STATE_DIR / "fixtures" / "api-pull.json"; content = [{"id": "fixture-1", "slug": "fixture-post", "title": "Fixture post", "content": "<p>Fixture content.</p>", "status": "published"}]
+    else:
+        output = root / STATE_DIR / "generated" / f"{args.target}.json"
+        content = {"type": args.target, "schema": "Maggie blog contract", "required": {"post": ["id", "slug", "title", "content", "status", "canonicalUrl", "publishedAt", "updatedAt", "author"], "topic": ["id", "slug", "title", "description"], "author": ["id", "slug", "name"], "migration": ["source", "sourceId", "mode", "checksum"], "seo": ["title", "description", "canonical", "robots", "jsonLd"], "ops-page": ["route", "auth", "api"]}[args.target]}
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(content, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    if args.target == "post":
+        generated = output.parent
+        (generated / "post.frontmatter.md").write_text("---\nid: stable-source-id\nslug: stable-public-slug\ntitle: Post title\nstatus: draft\ncanonicalUrl: https://example.com/blog/stable-public-slug\npublishedAt: null\nupdatedAt: null\nauthor: imported\n---\n\n# Post title\n\nContent goes here.\n", encoding="utf-8")
+        (generated / "post.types.ts").write_text("export type MaggiePost = { id: string; slug: string; title: string; content: string; status: 'draft' | 'review' | 'approved' | 'scheduled' | 'published' | 'archived'; canonicalUrl: string; publishedAt?: string; updatedAt?: string; author: { id: string; name: string } };\n", encoding="utf-8")
+        (generated / "post.fixture.json").write_text(json.dumps({"id":"fixture-post","slug":"fixture-post","title":"Fixture post","content":"<p>Fixture content.</p>","status":"draft","canonicalUrl":"https://example.com/blog/fixture-post","author":{"id":"author-imported","name":"Imported author"}}, indent=2) + "\n", encoding="utf-8")
+        (generated / "post.api.md").write_text("# Post API contract\n\nWrites must validate the fixed MaggiePost shape, create a revision, and require an explicit approval transition before publishing.\n", encoding="utf-8")
+    if args.target == "seo":
+        (output.parent / "seo.metadata.ts").write_text("export const robots = 'index,follow';\nexport const schemaType = 'Article';\nexport const jsonLdFields = ['@context','@type','headline','description','url','datePublished','dateModified','author'];\n", encoding="utf-8")
+    if args.target == "migration":
+        (output.parent / "migration.sql").write_text("-- Apply through the selected adapter; never bypass source_id/checksum idempotency.\nALTER TABLE posts ADD COLUMN source_id TEXT;\n", encoding="utf-8")
+        (output.parent / "migration.api.md").write_text("# Migration API contract\n\nPreview before apply. Every record requires `sourceId`, a normalized slug, a checksum, and a rollback identifier.\n", encoding="utf-8")
+    if args.target in {"topic", "author"}:
+        (output.parent / f"{args.target}.types.ts").write_text(f"export type Maggie{args.target.title()} = {{ id: string; slug: string; title: string; }};\n" if args.target == "topic" else "export type MaggieAuthor = { id: string; slug: string; name: string; credentials?: string[] };\n", encoding="utf-8")
+    if args.target == "ops-page":
+        (output.parent / "ops-page.api.md").write_text("# Ops page contract\n\nThe page is authenticated, calls a server-side `/api/ops/*` route, and must not expose provider credentials.\n", encoding="utf-8")
+    print(f"Generated contract artifact: {output}")
+    return 0
+
+
+def command_doctor(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve()
+    if getattr(args, "ci", False): args.strict = True
+    if args.require_bootstrap:
+        require_bootstrap(root)
+    files = list(files_for(root))
+    source_files = [
+        path for path in files
+        if path.suffix in {".astro", ".css", ".html", ".js", ".jsx", ".md", ".mdx", ".njk", ".svelte", ".ts", ".tsx", ".vue"}
+        and path.name.lower() not in {"readme.md", "changelog.md"}
+        and not any(part.lower() in {"docs", "documentation", "references"} for part in path.parts)
+    ]
+    text = "\n".join(read_text(path) for path in source_files)
+    paths = [evidence(path, root).lower() for path in source_files]
+
+    checks = {
+        "posts_route": any("post" in path for path in paths),
+        "sitemap_route": any("sitemap" in path for path in paths) or "sitemap" in text.lower(),
+        "robots_route": any("robots" in path for path in paths) or "robots" in text.lower(),
+        "post_identity_fields": all(token in text for token in ("id", "slug", "title")),
+        "publication_guard": all(token in text for token in ("status", "published", "publishedAt")),
+        "source_identity_or_sync": any(token in text for token in ("sourceId", "content_id", "sync_state", "syncState")),
+        "canonical_metadata": "canonical" in text.lower(),
+        "absolute_canonical": "https://" in text and "canonical" in text.lower(),
+        "meta_description": "description" in text.lower(),
+        "open_graph_metadata": "og:title" in text.lower() or "property=\"og:" in text.lower(),
+        "open_graph_url": "og:url" in text.lower(),
+        "twitter_card": "twitter:card" in text.lower(),
+        "article_jsonld": "application/ld+json" in text.lower() and ("article" in text.lower() or "blogposting" in text.lower()),
+        "jsonld_dates": "datePublished" in text and ("dateModified" in text or "updatedAt" in text),
+        "published_only_guard": "published" in text.lower() and any(token in text.lower() for token in {"sitemap", "post"}),
+        "no_public_api_key": not bool(re.search(r"(?:PUBLIC|NEXT_PUBLIC)[A-Z0-9_]*(?:API|KEY|TOKEN)", text, re.IGNORECASE)),
+        "no_placeholder_metadata": not any(token in text.lower() for token in {"your-domain.com", "example.com", "lorem ipsum", "replace-me"}),
+    }
+    if args.strict:
+        checks.update({
+            "topic_surface": any("topic" in path for path in paths),
+            "topic_description": "topic" in text.lower() and "description" in text.lower(),
+            "faq_surface": "faq" in text.lower(),
+            "cta_surface": "cta" in text.lower(),
+            "pagination_surface": "pagination" in text.lower() or "page_size" in text.lower(),
+            "eeat_authorship": "author" in text.lower() and ("credential" in text.lower() or "organisation" in text.lower() or "organization" in text.lower()),
+            "modified_date": "dateModified" in text or "updatedAt" in text,
+            "ops_surface": any("ops" in path for path in paths),
+            "ops_authentication": "auth" in text.lower() or "middleware" in text.lower(),
+            "integration_config": "AI_CMO_API_KEY" in text or "measurement_id" in text.lower() or "verification" in text.lower(),
+            "bootstrap_contract": all((root / STATE_DIR / filename).exists() for filename in ("project.json", "decisions.json", "schema.json", "routes.json", "integrations.json", "migration.json")),
+            "scheduled_publication_state": "scheduled" in text.lower() and "published" in text.lower(),
+            "revision_or_audit_trail": "revision" in text.lower() or "audit" in text.lower(),
+            "migration_checksum": "checksum" in text.lower() or "source_id" in text.lower(),
+            "private_ops_noindex": "noindex" in text.lower() and "ops" in text.lower(),
+            "consent_aware_analytics": "consent" in text.lower() and ("GA4" in text or "analytics" in text.lower()),
+            "migration_formats": all(format_name in text.lower() for format_name in ("csv", "json", "sitemap", "media-archive")),
+        })
+    safe_fixes: list[str] = []
+    safe_skips: list[str] = []
+    if getattr(args, "fix_safe", False):
+        package, _ = package_info(root)
+        is_astro = "astro" in dependency_names(package) or any(path.suffix == ".astro" for path in files)
+        pages_dir = root / "src" / "pages"
+        if is_astro and not checks["sitemap_route"]:
+            target = pages_dir / "sitemap.xml.ts"
+            if not target.exists():
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text("import type { APIRoute } from 'astro';\n\nexport const GET: APIRoute = () => new Response('<?xml version=\"1.0\" encoding=\"UTF-8\"?><urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\"></urlset>', { headers: { 'content-type': 'application/xml; charset=utf-8' } });\n", encoding="utf-8")
+                safe_fixes.append("created empty public sitemap route")
+        elif not checks["sitemap_route"]:
+            safe_skips.append("sitemap route requires framework confirmation")
+        if is_astro and not checks["robots_route"]:
+            target = pages_dir / "robots.txt.ts"
+            if not target.exists():
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text("import type { APIRoute } from 'astro';\n\nexport const GET: APIRoute = () => new Response('User-agent: *\\nAllow: /\\nDisallow: /ops\\nDisallow: /api\\n', { headers: { 'content-type': 'text/plain; charset=utf-8' } });\n", encoding="utf-8")
+                safe_fixes.append("created robots route with private-path disallow rules")
+        elif not checks["robots_route"]:
+            safe_skips.append("robots route requires framework confirmation")
+        for check, reason in (("canonical_metadata", "canonical metadata needs a site-specific URL"), ("meta_description", "metadata content needs editorial input"), ("article_jsonld", "JSON-LD shape needs content-specific fields")):
+            if not checks[check]: safe_skips.append(reason)
+    result = {"project_root": str(root), "checks": {key: {"ok": value} for key, value in checks.items()}, "passed": all(checks.values())}
+    if getattr(args, "fix_safe", False): result["safe_fixes"] = {"applied": safe_fixes, "skipped_requires_confirmation": safe_skips}
+    print(json.dumps(result, indent=2))
+    return 0 if result["passed"] else 1
+
+
+def command_contract_check(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve()
+    if args.kind == "seo":
+        args.require_bootstrap = False; args.strict = True; args.ci = False; args.fix_safe = False
+        return command_doctor(args)
+    if args.kind == "routes":
+        manifest = root / STATE_DIR / "routes.json"
+        if manifest.exists(): print(manifest.read_text(encoding="utf-8"), end="")
+        else: print(json.dumps({"routes": sorted(path for path in (evidence(item, root) for item in files_for(root)) if "route" in path.lower() or "sitemap" in path.lower())}, indent=2))
+        return 0
+    if args.kind == "env":
+        package, _ = package_info(root); example = root / ".env.example"; required = ["PUBLIC_SITE_URL", "AI_CMO_API_KEY", "BLOG_DB_PATH"]
+        found = set(re.findall(r"^([A-Z][A-Z0-9_]+)=", read_text(example), re.MULTILINE))
+        result = {"package": bool(package), "env_example": example.exists(), "required_variables_documented": {name: name in found for name in required}}
+        print(json.dumps(result, indent=2)); return 0 if result["env_example"] else 1
+    state = load_state(root); contract = root / STATE_DIR / ("schema.json" if args.kind == "schema" else "migration.json")
+    result = {"bootstrap": bool(state and state.get("status") == "completed"), "contract": str(contract), "contract_exists": contract.exists()}
+    print(json.dumps(result, indent=2)); return 0 if result["bootstrap"] and result["contract_exists"] else 1
+
+
+def command_fixture(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve(); require_bootstrap(root)
+    output = root / STATE_DIR / "fixtures"; output.mkdir(parents=True, exist_ok=True)
+    payloads = {
+        "wordpress": {"posts": [{"id": 1, "slug": "fixture-wordpress-post", "title": "Fixture WordPress post", "status": "publish"}], "categories": [{"id": 1, "name": "Guides", "slug": "guides"}], "tags": [{"id": 1, "name": "SEO", "slug": "seo"}], "media": []},
+        "api-pull": [{"id": "api-1", "slug": "fixture-api-post", "title": "Fixture API Pull post", "status": "published", "content": "<p>Fixture content.</p>"}],
+        "reports": {"visibility": {"clicks": 10, "impressions": 100, "period": "2026-08"}, "analytics": {"sessions": 20, "engagedSessions": 15, "period": "2026-08"}},
+        "sitemap-matching": {"sitemapUrl": "https://example.com/sitemap.xml", "sitemaps": 1, "totalPosts": 2, "matchedPosts": 1, "eligible": 1, "unmatched": 1, "items": [{"url": "https://example.com/blog/fixture-post", "postId": "fixture-post", "matched": True}]},
+        "rewrite-queue": [{"postId": "fixture-post", "reason": "fixture sitemap match", "status": "queued", "priority": 10}],
+    }
+    if args.fixture_command == "seed":
+        (output / "api-pull.json").write_text(json.dumps(payloads["api-pull"], indent=2) + "\n", encoding="utf-8")
+        (output / "sitemap-matching.json").write_text(json.dumps(payloads["sitemap-matching"], indent=2) + "\n", encoding="utf-8")
+        (output / "rewrite-queue.json").write_text(json.dumps(payloads["rewrite-queue"], indent=2) + "\n", encoding="utf-8")
+        (output / "reports.json").write_text(json.dumps(payloads["reports"], indent=2) + "\n", encoding="utf-8")
+        print(f"Seed fixtures: {output}")
+    else:
+        destination = output / f"{args.fixture_command}.json"; destination.write_text(json.dumps(payloads[args.fixture_command], indent=2) + "\n", encoding="utf-8"); print(f"Generated fixture: {destination}")
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="maggie", description=__doc__)
+    sub = p.add_subparsers(dest="command", required=True)
+    analyze = sub.add_parser("analyze", help="inspect a project without editing it")
+    analyze.add_argument("project", nargs="?", default=".")
+    analyze.add_argument("--json", action="store_true")
+    analyze.add_argument("--save", action="store_true", help="save analysis to .maggie/analysis.json")
+    analyze.set_defaults(func=command_analyze)
+    status = sub.add_parser("status", help="show bootstrap state")
+    status.add_argument("project", nargs="?", default=".")
+    status.set_defaults(func=command_status)
+    bootstrap = sub.add_parser("bootstrap", help="manage bootstrap state")
+    bootstrap_sub = bootstrap.add_subparsers(dest="bootstrap_command", required=True)
+    complete = bootstrap_sub.add_parser("complete", help="write state after explicit user confirmations")
+    complete.add_argument("project", nargs="?", default=".")
+    complete.add_argument("--confirm", action="append", choices=["foundation", "experience", "data", "publishing"], required=True)
+    for name, default in (("framework", "detected"), ("language", "detected"), ("content-language", "confirmed"), ("ui-system", "preserve-or-tailwind"), ("icon-set", "preserve-or-heroicons"), ("font", "preserve-or-system"), ("database", "preserve-or-sqlite"), ("content-source", "confirmed")):
+        complete.add_argument("--" + name, dest=name.replace("-", "_"), default=default)
+    complete.set_defaults(func=command_complete)
+    generate = sub.add_parser("generate", help="generate stable contract or fixture files")
+    generate.add_argument("target", choices=["contract", "fixture", "post", "topic", "author", "migration", "seo", "ops-page"])
+    generate.add_argument("project", nargs="?", default=".")
+    generate.set_defaults(func=command_generate)
+    fixture = sub.add_parser("fixture", help="generate deterministic local provider fixtures")
+    fixture_sub = fixture.add_subparsers(dest="fixture_command", required=True)
+    for fixture_name in ("seed", "wordpress", "api-pull", "reports", "sitemap-matching", "rewrite-queue"):
+        item = fixture_sub.add_parser(fixture_name)
+        item.add_argument("project", nargs="?", default=".")
+        item.set_defaults(func=command_fixture)
+    doctor = sub.add_parser("doctor", help="check blog routes and SEO output invariants")
+    doctor.add_argument("project", nargs="?", default=".")
+    doctor.add_argument("--require-bootstrap", action="store_true")
+    doctor.add_argument("--strict", action="store_true", help="also require the complete AI-native blog and Ops surface")
+    doctor.add_argument("--ci", action="store_true", help="CI alias for strict checks")
+    doctor.add_argument("--fix-safe", action="store_true", help="apply only low-risk route fixes; never changes schema, slugs, canonical URLs or publishing state")
+    doctor.set_defaults(func=command_doctor)
+    for name in ("routes", "schema", "seo", "migration", "env"):
+        check = sub.add_parser(name, help=f"run Maggie {name} contract checks")
+        check.add_argument("project", nargs="?", default=".")
+        if name in {"schema", "seo", "migration"}: check.set_defaults(kind=name)
+        else: check.set_defaults(kind=name)
+        check.set_defaults(func=command_contract_check)
+
+    api = sub.add_parser("api", help="call an AI CMO API Pull endpoint safely")
+    api_sub = api.add_subparsers(dest="api_command", required=True)
+
+    def api_options(command: argparse.ArgumentParser, project: bool = False, execute: bool = False) -> None:
+        command.add_argument("--base-url", default=None)
+        command.add_argument("--timeout", type=int, default=30)
+        command.add_argument("--output", help="persist the JSON response atomically")
+        if project:
+            command.add_argument("--project", default=".")
+        if execute:
+            command.add_argument("--execute", action="store_true", help="send the request; otherwise remain dry-run")
+
+    get = api_sub.add_parser("get", help="read an endpoint")
+    get.add_argument("path", choices=["/whoami", "/project-context", "/posts", "/updates", "/history", "/latest", "/rewrite-policy", "/sitemap/matching-history", "/rewrite/queue", "/quota"])
+    get.add_argument("--charges-quota", action="store_true", help="mark delivery endpoints as quota-consuming")
+    api_options(get, project=True, execute=True)
+    get.set_defaults(func=command_api_get, requires_bootstrap=False)
+
+    sitemap = api_sub.add_parser("sitemap", help="match or inspect sitemap history")
+    sitemap_sub = sitemap.add_subparsers(dest="sitemap_command", required=True)
+    match = sitemap_sub.add_parser("match", help="match a supplied sitemap URL")
+    match.add_argument("--sitemap-url", required=True)
+    match.add_argument("--project", default=".")
+    match.add_argument("--execute", action="store_true")
+    match.add_argument("--base-url", default=None)
+    match.add_argument("--timeout", type=int, default=30)
+    match.add_argument("--output")
+    match.add_argument("--idempotency-key")
+    match.add_argument("path", nargs="?", default="/sitemap/match", help=argparse.SUPPRESS)
+    match.set_defaults(func=command_api_post, requires_bootstrap=True)
+    auto = sitemap_sub.add_parser("auto-detect", help="discover and match domain sitemaps")
+    auto.add_argument("--project", default=".")
+    auto.add_argument("--execute", action="store_true")
+    auto.add_argument("--base-url", default=None)
+    auto.add_argument("--timeout", type=int, default=30)
+    auto.add_argument("--output")
+    auto.add_argument("--idempotency-key")
+    auto.add_argument("path", nargs="?", default="/sitemap/auto-detect", help=argparse.SUPPRESS)
+    auto.set_defaults(func=command_api_post, requires_bootstrap=True)
+    history = sitemap_sub.add_parser("history", help="read persisted matching history")
+    history.add_argument("path", nargs="?", default="/sitemap/matching-history", help=argparse.SUPPRESS)
+    api_options(history)
+    history.set_defaults(func=command_api_get, charges_quota=False)
+
+    pull = api_sub.add_parser("pull", help="deliver or inspect API Pull content")
+    pull_sub = pull.add_subparsers(dest="pull_command", required=True)
+    for name, path, charges in (("posts", "/posts", True), ("updates", "/updates", True), ("history", "/history", False), ("latest", "/latest", False)):
+        item = pull_sub.add_parser(name)
+        item.add_argument("path", nargs="?", default=path, help=argparse.SUPPRESS)
+        api_options(item, project=charges, execute=charges)
+        item.set_defaults(func=command_api_get, charges_quota=charges, requires_bootstrap=charges)
+
+    rewrite = api_sub.add_parser("rewrite", help="inspect or explicitly queue rewrites")
+    rewrite_sub = rewrite.add_subparsers(dest="rewrite_command", required=True)
+    queue = rewrite_sub.add_parser("queue")
+    queue.add_argument("path", nargs="?", default="/rewrite/queue", help=argparse.SUPPRESS)
+    api_options(queue)
+    queue.set_defaults(func=command_api_get, charges_quota=False)
+    request = rewrite_sub.add_parser("request", help="queue one rewrite from a JSON body")
+    request.add_argument("--body-file", required=True)
+    request.add_argument("--project", default=".")
+    request.add_argument("--execute", action="store_true")
+    request.add_argument("--base-url", default=None)
+    request.add_argument("--timeout", type=int, default=30)
+    request.add_argument("--output")
+    request.add_argument("--idempotency-key")
+    request.add_argument("path", nargs="?", default="/rewrite/queue", help=argparse.SUPPRESS)
+    request.set_defaults(func=command_api_post, requires_bootstrap=True)
+    rhistory = rewrite_sub.add_parser("history")
+    rhistory.add_argument("content_id")
+    rhistory.add_argument("--base-url", default=None)
+    rhistory.add_argument("--timeout", type=int, default=30)
+    rhistory.add_argument("path", nargs="?", default=None, help=argparse.SUPPRESS)
+    rhistory.set_defaults(func=command_rewrite_history, charges_quota=False)
+
+    policy = api_sub.add_parser("policy", help="read or update rewrite policy")
+    policy_sub = policy.add_subparsers(dest="policy_command", required=True)
+    policy_get = policy_sub.add_parser("get")
+    policy_get.add_argument("path", nargs="?", default="/rewrite-policy", help=argparse.SUPPRESS)
+    api_options(policy_get)
+    policy_get.set_defaults(func=command_api_get, charges_quota=False)
+    policy_set = policy_sub.add_parser("set")
+    policy_set.add_argument("--body-file", required=True)
+    policy_set.add_argument("--project", default=".")
+    policy_set.add_argument("--execute", action="store_true")
+    policy_set.add_argument("--base-url", default=None)
+    policy_set.add_argument("--timeout", type=int, default=30)
+    policy_set.add_argument("--output")
+    policy_set.add_argument("--idempotency-key")
+    policy_set.add_argument("path", nargs="?", default="/rewrite-policy", help=argparse.SUPPRESS)
+    policy_set.set_defaults(func=command_api_post, requires_bootstrap=True)
+
+    report = api_sub.add_parser("report-state", help="report observed local publication state")
+    report.add_argument("--body-file", required=True)
+    report.add_argument("--project", default=".")
+    report.add_argument("--execute", action="store_true")
+    report.add_argument("--base-url", default=None)
+    report.add_argument("--timeout", type=int, default=30)
+    report.add_argument("--output")
+    report.add_argument("--idempotency-key")
+    report.add_argument("path", nargs="?", default="/content-tracking/report-state", help=argparse.SUPPRESS)
+    report.set_defaults(func=command_api_post, requires_bootstrap=True)
+    return p
+
+
+if __name__ == "__main__":
+    arguments = parser().parse_args()
+    raise SystemExit(arguments.func(arguments))