@topy-ai/maggie 0.7.40 → 0.7.42

package/bundled-tools/clis/maggie_workflows.py

@@ -0,0 +1,439 @@
+#!/usr/bin/env python3
+"""Stable, read-only policy and evidence gates for deferred Maggie workflows."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import html
+import json
+import shutil
+import subprocess
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def contract_root() -> Path:
+    tool_path = Path(__file__).resolve()
+    bundled_tools = next((path for path in tool_path.parents if path.name == "bundled-tools"), None)
+    if bundled_tools:
+        return bundled_tools.parent / "bundled-contracts"
+    return ROOT / "contracts"
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def load(path: Path) -> dict:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return value
+
+
+def emit(value: dict, output: str | None = None) -> int:
+    if output:
+        target = Path(output).expanduser().resolve()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps(value, indent=2, ensure_ascii=False))
+    return 0 if value.get("passed") is True else 1
+
+
+def validate_media(args: argparse.Namespace) -> int:
+    policy = load(Path(args.policy).expanduser().resolve())
+    kind = args.kind
+    expected = f"maggie-{kind}-generation-policy.v1"
+    errors: list[str] = []
+    if policy.get("schemaVersion") != expected:
+        errors.append(f"schemaVersion must be {expected}")
+    if policy.get("provider") != "google-gemini":
+        errors.append("provider must be google-gemini")
+    if not str(policy.get("model", "")).startswith("gemini-"):
+        errors.append("model must be a Gemini model id")
+    if not str(policy.get("fallbackModel", "")).startswith(("gemini-", "veo-")):
+        errors.append("fallbackModel must be a Gemini or Veo model id")
+    if policy.get("endpointEnv") != "GEMINI_API_ENDPOINT" or policy.get("apiKeyEnv") != "GEMINI_API_KEY":
+        errors.append("Gemini endpoint and key must remain host environment names")
+    rights = policy.get("rights") if isinstance(policy.get("rights"), dict) else {}
+    moderation = policy.get("moderation") if isinstance(policy.get("moderation"), dict) else {}
+    for key in ("inputRightsRequired", "outputReviewRequired"):
+        if rights.get(key) is not True:
+            errors.append(f"rights.{key} must be true")
+    for key in ("preflightRequired", "postGenerationReviewRequired"):
+        if moderation.get(key) is not True:
+            errors.append(f"moderation.{key} must be true")
+    if kind == "image":
+        outputs = policy.get("outputs") if isinstance(policy.get("outputs"), dict) else {}
+        if not outputs.get("allowedMimeTypes") or not outputs.get("allowedSizes"):
+            errors.append("image outputs must declare mime types and sizes")
+    else:
+        cost = policy.get("costPolicy") if isinstance(policy.get("costPolicy"), dict) else {}
+        storage = policy.get("storage") if isinstance(policy.get("storage"), dict) else {}
+        if cost.get("budgetRequired") is not True or cost.get("duplicateChargeProtection") != "idempotency-key":
+            errors.append("video cost policy must require a budget and idempotency protection")
+        if storage.get("adapter") != "host-owned-object-storage":
+            errors.append("video storage must remain host-owned-object-storage")
+    provenance = policy.get("provenance")
+    if not isinstance(provenance, list) or not {"model", "sourceRevision", "createdAt"}.issubset(provenance):
+        errors.append("policy provenance must include model, sourceRevision, and createdAt")
+    return emit({"schemaVersion": expected, "passed": not errors, "kind": kind, "provider": policy.get("provider"), "model": policy.get("model"), "fallbackModel": policy.get("fallbackModel"), "errors": errors, "credentialsPrinted": False}, args.output)
+
+
+def validate_video_job(args: argparse.Namespace) -> int:
+    job = load(Path(args.job).expanduser().resolve())
+    errors: list[str] = []
+    if job.get("schemaVersion") != "maggie-video-job.v1":
+        errors.append("schemaVersion must be maggie-video-job.v1")
+    for key in ("jobId", "idempotencyKey", "sourceRevision", "provenance"):
+        if not job.get(key):
+            errors.append(f"{key} is required")
+    state = job.get("state")
+    attempt = job.get("attempt")
+    if state == "retrying" and (not isinstance(attempt, int) or attempt < 1 or attempt > 3):
+        errors.append("retrying jobs need attempt between 1 and 3")
+    if state == "dead-letter" and job.get("errorClass") not in {"provider-permanent", "moderation", "rights", "validation", "cost-limit", "unknown"}:
+        errors.append("dead-letter jobs need a terminal errorClass")
+    if state == "completed" and not isinstance(job.get("storage"), dict):
+        errors.append("completed jobs need host storage evidence")
+    return emit({"schemaVersion": "maggie-video-job.v1", "passed": not errors, "jobId": job.get("jobId"), "state": state, "errors": errors, "rawProviderPayloadIncluded": False}, args.output)
+
+
+def validate_video_provider_evidence(args: argparse.Namespace) -> int:
+    evidence = load(Path(args.evidence).expanduser().resolve())
+    errors: list[str] = []
+    allowed = {
+        "schemaVersion", "environment", "provider", "model", "status", "hostVerified",
+        "acknowledgement", "idempotency", "moderation", "storage", "retry",
+        "rawProviderPayloadIncluded", "inputAssetDataIncluded", "sourceRevision", "generatedAt",
+    }
+    for key in evidence:
+        if key not in allowed:
+            errors.append(f"evidence.{key} is not allowed")
+    nested_allowed = {
+        "acknowledgement": {"accepted", "providerReferencePresent"},
+        "idempotency": {"replayAccepted", "duplicateChargePrevented", "assetDeduplicated"},
+        "moderation": {"preflightPassed", "postGenerationReviewPassed"},
+        "storage": {"uploadAccepted", "metadataPersisted", "readbackPassed", "signedOrApprovedUrlPresent"},
+        "retry": {"transientFailureObserved", "bounded", "attempts"},
+        "sourceRevision": {"commit", "branch", "dirty"},
+    }
+    for parent, keys in nested_allowed.items():
+        value = evidence.get(parent)
+        if isinstance(value, dict):
+            for key in value:
+                if key not in keys:
+                    errors.append(f"{parent}.{key} is not allowed")
+    if evidence.get("schemaVersion") != "maggie-video-provider-evidence.v1": errors.append("schemaVersion must be maggie-video-provider-evidence.v1")
+    if evidence.get("environment") not in {"test", "staging", "production"}: errors.append("environment is unsupported")
+    if evidence.get("provider") != "google-gemini": errors.append("provider must be google-gemini")
+    if not str(evidence.get("model", "")).startswith(("gemini-", "veo-")): errors.append("model must be a Gemini or Veo model id")
+    if evidence.get("status") != "passed": errors.append("status must be passed")
+    if args.require_host and evidence.get("hostVerified") is not True: errors.append("hostVerified must be true")
+    acknowledgement = evidence.get("acknowledgement") if isinstance(evidence.get("acknowledgement"), dict) else {}
+    if acknowledgement.get("accepted") is not True or acknowledgement.get("providerReferencePresent") is not True: errors.append("provider acknowledgement is incomplete")
+    idempotency = evidence.get("idempotency") if isinstance(evidence.get("idempotency"), dict) else {}
+    if any(idempotency.get(key) is not True for key in ("replayAccepted", "duplicateChargePrevented", "assetDeduplicated")): errors.append("video idempotency evidence is incomplete")
+    moderation = evidence.get("moderation") if isinstance(evidence.get("moderation"), dict) else {}
+    if moderation.get("preflightPassed") is not True or moderation.get("postGenerationReviewPassed") is not True: errors.append("moderation evidence is incomplete")
+    storage = evidence.get("storage") if isinstance(evidence.get("storage"), dict) else {}
+    if any(storage.get(key) is not True for key in ("uploadAccepted", "metadataPersisted", "readbackPassed", "signedOrApprovedUrlPresent")): errors.append("storage readback evidence is incomplete")
+    retry = evidence.get("retry") if isinstance(evidence.get("retry"), dict) else {}
+    attempts = retry.get("attempts")
+    if retry.get("transientFailureObserved") is not True or retry.get("bounded") is not True or not isinstance(attempts, int) or attempts < 1 or attempts > 3: errors.append("retry evidence is incomplete")
+    if evidence.get("rawProviderPayloadIncluded") is not False: errors.append("raw provider payloads must be excluded")
+    if evidence.get("inputAssetDataIncluded") is not False: errors.append("input asset data must be excluded")
+    source = evidence.get("sourceRevision") if isinstance(evidence.get("sourceRevision"), dict) else {}
+    if not isinstance(source.get("commit"), str) or not isinstance(source.get("branch"), str) or not isinstance(source.get("dirty"), bool): errors.append("sourceRevision is incomplete")
+    if args.environment and evidence.get("environment") != args.environment: errors.append("environment does not match workflow input")
+    if args.model and evidence.get("model") != args.model: errors.append("model does not match workflow input")
+    return emit({"schemaVersion": "maggie-video-provider-evidence.v1", "passed": not errors, "environment": evidence.get("environment"), "provider": evidence.get("provider"), "model": evidence.get("model"), "errors": errors, "rawProviderPayloadIncluded": False, "redacted": True}, args.output)
+
+
+def git_value(project: Path, *args: str) -> str:
+    result = subprocess.run(["git", "-C", str(project), *args], capture_output=True, text=True, check=False)
+    if result.returncode:
+        raise ValueError(result.stderr.strip() or "not a git worktree")
+    return result.stdout.strip()
+
+
+def capture_provenance(args: argparse.Namespace) -> int:
+    project = Path(args.project).expanduser().resolve()
+    source = Path(args.source).expanduser().resolve() if args.source else project
+    try:
+        relative = source.relative_to(project).as_posix() or "."
+    except ValueError as error:
+        raise ValueError("--source must be inside --project") from error
+    if any(part in {".env", ".git", "node_modules"} for part in source.parts):
+        raise ValueError("source cannot be a secret, git metadata, or dependency path")
+    commit = git_value(project, "rev-parse", "HEAD")
+    branch = git_value(project, "branch", "--show-current") or "detached"
+    dirty = bool(git_value(project, "status", "--porcelain", "--", relative))
+    tracked = subprocess.run(["git", "-C", str(project), "ls-files", "--error-unmatch", relative], capture_output=True, text=True, check=False).returncode == 0
+    value = {"schemaVersion": "maggie-content-provenance.v1", "commit": commit, "branch": branch, "dirty": dirty, "sourceRevision": commit, "sourcePath": relative, "authoringBoundary": args.boundary, "tracked": tracked, "staleWritePolicy": "reject-unless-source-revision-matches", "capturedAt": now()}
+    # capturedAt is useful in a report but not part of the contract artifact.
+    return emit({**value, "passed": True}, args.output)
+
+
+FRAMEWORK_PACKAGES = {
+    "astro": ["astro"],
+    "nextjs": ["next", "react", "react-dom"],
+    "sveltekit": ["@sveltejs/kit"],
+    "nuxt": ["nuxt"],
+    "vite-react": ["vite", "react", "react-dom"],
+    "vite-vue": ["vite", "vue"],
+}
+
+NPM_SUPPORT_MATRIX = [
+    {"packageManager": "npm", "supportedVersions": ["11.x"], "installCommand": "npm install", "lockfile": "package-lock-v3", "lifecyclePolicy": "ignore-scripts-smoke-first"},
+    {"packageManager": "pnpm", "supportedVersions": ["9.x", "10.x"], "installCommand": "pnpm install", "lockfile": "pnpm-lock.yaml", "lifecyclePolicy": "ignore-scripts-smoke-first"},
+    {"packageManager": "yarn", "supportedVersions": ["1.x", "4.x"], "installCommand": "yarn install", "lockfile": "yarn.lock", "lifecyclePolicy": "ignore-scripts-smoke-first"},
+    {"packageManager": "bun", "supportedVersions": ["1.x"], "installCommand": "bun install", "lockfile": "bun.lock", "lifecyclePolicy": "ignore-scripts-smoke-first"},
+]
+
+
+def scaffold_files(framework: str, language: str) -> dict[str, str]:
+    typed = language == "typescript"
+    if framework == "astro":
+        return {
+            "astro.config.mjs": "import { defineConfig } from 'astro/config';\n\nexport default defineConfig();\n",
+            f"src/pages/index.{'astro'}": "---\nconst title = 'Maggie project';\n---\n<html lang=\"en\">\n  <head><meta charset=\"utf-8\" /><meta name=\"viewport\" content=\"width=device-width\" /><title>{title}</title></head>\n  <body><main><h1>{title}</h1><p>Generated by Maggie.</p></main></body>\n</html>\n",
+        }
+    if framework == "nextjs":
+        extension = "tsx" if typed else "jsx"
+        return {
+            f"app/layout.{extension}": "export default function RootLayout({ children }) { return <html lang=\"en\"><body>{children}</body></html>; }\n",
+            f"app/page.{extension}": "export default function Home() { return <main><h1>Maggie project</h1><p>Generated by Maggie.</p></main>; }\n",
+            "next.config.mjs": "/** @type {import('next').NextConfig} */\nconst nextConfig = {};\nexport default nextConfig;\n",
+        }
+    if framework == "sveltekit":
+        return {
+            "src/routes/+page.svelte": "<svelte:head><title>Maggie project</title></svelte:head>\n<main><h1>Maggie project</h1><p>Generated by Maggie.</p></main>\n",
+            "svelte.config.js": "import adapter from '@sveltejs/adapter-auto';\nexport default { kit: { adapter: adapter() } };\n",
+            "vite.config.js": "import { sveltekit } from '@sveltejs/kit/vite';\nimport { defineConfig } from 'vite';\nexport default defineConfig({ plugins: [sveltekit()] });\n",
+        }
+    if framework == "nuxt":
+        extension = "ts" if typed else "js"
+        return {
+            f"pages/index.vue": "<template><main><h1>Maggie project</h1><p>Generated by Maggie.</p></main></template>\n",
+            f"nuxt.config.{extension}": "export default defineNuxtConfig({});\n",
+        }
+    if framework == "vite-react":
+        extension = "tsx" if typed else "jsx"
+        return {
+            "index.html": "<div id=\"root\"></div><script type=\"module\" src=\"/src/main.%s\"></script>\n" % extension,
+            f"src/main.{extension}": "import React from 'react';\nimport { createRoot } from 'react-dom/client';\nimport App from './App';\nimport './style.css';\ncreateRoot(document.getElementById('root')).render(<React.StrictMode><App /></React.StrictMode>);\n",
+            f"src/App.{extension}": "export default function App() { return <main><h1>Maggie project</h1><p>Generated by Maggie.</p></main>; }\n",
+            "src/style.css": "body { margin: 0; font-family: system-ui, sans-serif; } main { padding: 3rem; }\n",
+        }
+    if framework == "vite-vue":
+        return {
+            "index.html": "<div id=\"app\"></div><script type=\"module\" src=\"/src/main.js\"></script>\n",
+            "src/main.js": "import { createApp } from 'vue';\nimport App from './App.vue';\nimport './style.css';\ncreateApp(App).mount('#app');\n",
+            "src/App.vue": "<template><main><h1>Maggie project</h1><p>Generated by Maggie.</p></main></template>\n",
+            "src/style.css": "body { margin: 0; font-family: system-ui, sans-serif; } main { padding: 3rem; }\n",
+        }
+    raise ValueError(f"unsupported scaffold framework: {framework}")
+
+
+def package_manifest(project: Path, framework: str, language: str, package_manager: str, packages: list[str]) -> dict:
+    extension = "ts" if language == "typescript" else "js"
+    scripts = {"dev": "astro dev", "build": "astro build", "preview": "astro preview"} if framework == "astro" else {
+        "dev": "next dev", "build": "next build", "start": "next start"} if framework == "nextjs" else {
+        "dev": "vite dev", "build": "vite build", "preview": "vite preview"}
+    if framework == "sveltekit": scripts = {"dev": "vite dev", "build": "vite build", "preview": "vite preview"}
+    if framework == "nuxt": scripts = {"dev": "nuxt dev", "build": "nuxt build", "preview": "nuxt preview"}
+    dev_dependencies = {package: "latest" for package in packages}
+    return {"name": project.name.lower().replace("_", "-") or "maggie-project", "private": True, "type": "module", "scripts": scripts, "packageManager": package_manager, "maggie": {"framework": framework, "language": language, "entryExtension": extension}, "devDependencies": dev_dependencies}
+
+
+def scaffold(args: argparse.Namespace) -> int:
+    project = Path(args.project).expanduser().resolve()
+    packages = FRAMEWORK_PACKAGES[args.framework]
+    generated = scaffold_files(args.framework, args.language)
+    manifest = {"schemaVersion": "maggie-host-scaffold.v1", "framework": args.framework, "language": args.language, "packageManager": args.package_manager, "installPolicy": {"requiresConfirm": True, "secretsByDefault": "never", "migrationsByDefault": "never", "installDependencies": bool(args.install_dependencies)}, "hostHandoff": {"generatedFiles": [".maggie/scaffold/manifest.json", *sorted(generated), "package.json"], "rollbackPlan": "remove generated files only and revert only the explicit dependency diff", "nextCommands": [f"maggie doctor --project {project}", "maggie ops preflight --project ."]}, "packages": packages, "createdAt": now()}
+    errors: list[str] = []
+    if args.install_dependencies and not args.confirm:
+        errors.append("--install-dependencies requires --confirm")
+    if args.write:
+        if errors:
+            return emit({"schemaVersion": "maggie-host-scaffold.v1", "passed": False, "errors": errors, "mutation": "not executed"}, args.output)
+        existing = [str(project / relative) for relative in [*generated, "package.json"] if (project / relative).exists()]
+        if existing and not args.force:
+            errors.append(f"refusing to overwrite existing scaffold files; use --force: {', '.join(existing[:5])}")
+            return emit({**manifest, "passed": False, "mutation": "not executed", "errors": errors}, args.output)
+        project.mkdir(parents=True, exist_ok=True)
+        package_path = project / "package.json"
+        package_path.write_text(json.dumps(package_manifest(project, args.framework, args.language, args.package_manager, packages), indent=2) + "\n", encoding="utf-8")
+        for relative, content in generated.items():
+            target = project / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+        target = project / ".maggie" / "scaffold" / "manifest.json"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        if args.install_dependencies:
+            install_cmd = [args.package_manager, "add" if args.package_manager in {"pnpm", "yarn", "bun"} else "install", *packages]
+            if args.package_manager == "npm":
+                install_cmd = ["npm", "install", *packages]
+            subprocess.run(install_cmd, cwd=project, check=True)
+    return emit({**manifest, "passed": not errors, "mutation": "executed" if args.write else "plan-only", "errors": errors}, args.output)
+
+
+def validate_brand(args: argparse.Namespace) -> int:
+    kit = load(Path(args.manifest).expanduser().resolve())
+    errors: list[str] = []
+    required = {"schemaVersion": "maggie-brand-kit.v1", "designBoundary": "DESIGN.md-and-host-tokens-are-source-of-truth"}
+    for key, expected in required.items():
+        if kit.get(key) != expected:
+            errors.append(f"{key} must be {expected}")
+    for key in ("designTokens", "logo", "typography", "icons", "assetManifest", "preview"):
+        if not kit.get(key):
+            errors.append(f"{key} is required")
+    if isinstance(kit.get("icons"), dict) and kit["icons"].get("policy") not in {"library-first", "host-defined"}:
+        errors.append("icons.policy must declare library-first or host-defined")
+    return emit({"schemaVersion": "maggie-brand-kit.v1", "passed": not errors, "errors": errors, "designTokensMutated": False}, args.output)
+
+
+def token_values(design_path: Path, token_path: Path | None) -> dict:
+    if token_path:
+        return load(token_path)
+    content = design_path.read_text(encoding="utf-8")
+    found = {name: value.strip() for name, value in __import__("re").findall(r"(--[A-Za-z0-9_-]+)\s*:\s*([^;\n]+)", content)}
+    return found or {"source": str(design_path), "contentHash": hashlib.sha256(content.encode()).hexdigest()}
+
+
+def brand_kit(args: argparse.Namespace) -> int:
+    project = Path(args.project).expanduser().resolve()
+    design_path = Path(args.design).expanduser().resolve() if args.design else project / "DESIGN.md"
+    token_path = Path(args.tokens).expanduser().resolve() if args.tokens else None
+    errors: list[str] = []
+    if not design_path.is_file(): errors.append(f"DESIGN.md is missing: {design_path}")
+    if token_path and not token_path.is_file(): errors.append(f"tokens file is missing: {token_path}")
+    if errors: return emit({"schemaVersion": "maggie-brand-kit.v1", "passed": False, "errors": errors, "designTokensMutated": False}, args.output)
+    design_tokens = token_values(design_path, token_path)
+    assets: list[str] = []
+    if args.assets:
+        asset_root = Path(args.assets).expanduser().resolve()
+        if not asset_root.is_dir(): errors.append(f"asset directory is missing: {asset_root}")
+        else: assets = [str(path.relative_to(project)) if path.is_relative_to(project) else str(path) for path in sorted(asset_root.rglob("*")) if path.is_file()]
+    kit = {"schemaVersion": "maggie-brand-kit.v1", "designTokens": design_tokens, "logo": {"primary": args.logo or "host-defined", "variants": ["primary", "monochrome"]}, "typography": {"families": [args.font or "host-defined"], "weights": [400, 500, 600, 700]}, "icons": {"library": args.icon_library, "policy": "library-first"}, "assetManifest": ".maggie/brand-kit/assets.json", "preview": ".maggie/brand-kit/preview.html", "designBoundary": "DESIGN.md-and-host-tokens-are-source-of-truth", "sources": {"design": str(design_path), "tokens": str(token_path) if token_path else None}}
+    if args.write:
+        if not args.confirm: errors.append("--write requires --confirm")
+        if not errors:
+            target = project / ".maggie" / "brand-kit"
+            target.mkdir(parents=True, exist_ok=True)
+            (target / "brand-kit.json").write_text(json.dumps(kit, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            (target / "assets.json").write_text(json.dumps({"schemaVersion": "maggie-brand-assets.v1", "assets": assets, "redacted": True}, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            swatches = "".join(f"<li><code>{html.escape(str(key))}</code><span style=\"background:{html.escape(str(value))}\"></span><small>{html.escape(str(value))}</small></li>" for key, value in design_tokens.items() if isinstance(value, (str, int, float)))
+            preview = "<!doctype html><meta charset=\"utf-8\"><title>Maggie brand kit preview</title><style>body{font:16px system-ui,sans-serif;max-width:60rem;margin:2rem auto;padding:0 1rem;color:#172033}ul{list-style:none;padding:0}li{display:flex;gap:.75rem;align-items:center;padding:.5rem 0;border-bottom:1px solid #ddd}li span{width:2rem;height:2rem;border:1px solid #aaa;border-radius:.35rem}small{color:#5b6472}</style><main><h1>Maggie brand kit</h1><p>Read-only preview generated from the approved DESIGN source.</p><h2>Design tokens</h2><ul>" + swatches + f"</ul><p>Logo: <code>{html.escape(str(kit['logo']['primary']))}</code></p><p>Icon library: <code>{html.escape(args.icon_library)}</code></p><p>Assets listed: {len(assets)}</p></main>\n"
+            (target / "preview.html").write_text(preview, encoding="utf-8")
+    return emit({**kit, "passed": not errors, "mutation": "executed" if args.write and not errors else "plan-only", "errors": errors, "designTokensMutated": False}, args.output)
+
+
+def npm11(args: argparse.Namespace) -> int:
+    project = Path(args.project).expanduser().resolve()
+    package_path = project / "package.json"
+    errors: list[str] = []
+    package: dict = {}
+    if not package_path.is_file():
+        errors.append("package.json is missing")
+    else:
+        package = load(package_path)
+    engines = package.get("engines") if isinstance(package.get("engines"), dict) else {}
+    scripts = package.get("scripts") if isinstance(package.get("scripts"), dict) else {}
+    node_version = subprocess.run(["node", "--version"], capture_output=True, text=True, check=False).stdout.strip()
+    npm_version = subprocess.run(["npm", "--version"], capture_output=True, text=True, check=False).stdout.strip()
+    try:
+        npm_major = int(npm_version.split(".", 1)[0])
+    except (ValueError, IndexError):
+        npm_major = None
+    required_node = str(engines.get("node") or ">=18")
+    lifecycle_scripts = sorted(set(scripts).intersection({"install", "preinstall", "postinstall"}))
+    if lifecycle_scripts and not (args.smoke and args.confirm):
+        errors.append("install lifecycle scripts require an explicit audited release decision")
+    if npm_major is not None and npm_major < 11:
+        errors.append("npm 11 is required for this preflight")
+    smoke = {"requested": bool(args.smoke), "ignoreScripts": True, "passed": not errors, "command": None, "stderr": None}
+    if args.smoke:
+        if not args.confirm: errors.append("--smoke requires --confirm because it performs an isolated dependency install")
+        elif not package_path.is_file(): errors.append("--smoke requires package.json")
+        else:
+            with tempfile.TemporaryDirectory(prefix="maggie-npm11-") as temporary:
+                sandbox = Path(temporary)
+                shutil.copy2(package_path, sandbox / "package.json")
+                if (project / "package-lock.json").is_file(): shutil.copy2(project / "package-lock.json", sandbox / "package-lock.json")
+                command = ["npm", "install", "--ignore-scripts", "--no-audit", "--no-fund", "--package-lock=false"]
+                proc = subprocess.run(command, cwd=sandbox, capture_output=True, text=True, check=False, timeout=300)
+                smoke.update({"command": "npm install --ignore-scripts --no-audit --no-fund --package-lock=false", "exitCode": proc.returncode, "stderr": proc.stderr[-500:] if proc.stderr else None, "passed": proc.returncode == 0})
+                if proc.returncode: errors.append("isolated npm install smoke failed")
+    result = {"schemaVersion": "maggie-npm11-preflight.v1", "supportMatrix": NPM_SUPPORT_MATRIX, "node": {"supportedMajor": required_node, "observedMajor": node_version}, "npm": {"supportedMajor": 11, "observedMajor": npm_version}, "installScriptPolicy": "ignore-scripts-smoke-first", "lockfilePolicy": "package-lock-v3" if (project / "package-lock.json").exists() else "host-package-manager", "smoke": smoke, "scripts": sorted(scripts), "lifecycleScripts": lifecycle_scripts, "errors": errors, "passed": not errors}
+    return emit(result, args.output)
+
+
+def validate_booking_delivery(args: argparse.Namespace) -> int:
+    policy = load(Path(args.policy).expanduser().resolve())
+    errors: list[str] = []
+    if policy.get("schemaVersion") != "maggie-booking-delivery-provider.v1":
+        errors.append("schemaVersion must be maggie-booking-delivery-provider.v1")
+    if policy.get("confirmationRule") != "provider-acknowledged-only":
+        errors.append("confirmationRule must be provider-acknowledged-only")
+    email = policy.get("email") if isinstance(policy.get("email"), dict) else {}
+    sms = policy.get("sms") if isinstance(policy.get("sms"), dict) else {}
+    if email.get("provider") not in {"resend", "provider-neutral"} or email.get("channel") != "email":
+        errors.append("email must use Resend or provider-neutral email")
+    if sms.get("provider") not in {"twilio", "provider-neutral"} or sms.get("channel") != "sms":
+        errors.append("sms must use Twilio or provider-neutral SMS")
+    retry = policy.get("retryPolicy") if isinstance(policy.get("retryPolicy"), dict) else {}
+    if retry.get("idempotency") != "booking-event-and-channel" or not isinstance(retry.get("maxAttempts"), int):
+        errors.append("retry policy must be idempotent and bounded")
+    dead = policy.get("deadLetterPolicy") if isinstance(policy.get("deadLetterPolicy"), dict) else {}
+    if dead.get("afterMaxAttempts") != "dead-letter" or dead.get("replayRequiresExplicitAction") is not True:
+        errors.append("dead-letter policy must require explicit replay")
+    return emit({"schemaVersion": "maggie-booking-delivery-provider.v1", "passed": not errors, "emailProvider": email.get("provider"), "smsProvider": sms.get("provider"), "errors": errors, "credentialsPrinted": False}, args.output)
+
+
+def validate_playback(args: argparse.Namespace) -> int:
+    evidence = load(Path(args.evidence).expanduser().resolve())
+    errors: list[str] = []
+    if evidence.get("schemaVersion") != "maggie-video-playback-evidence.v1": errors.append("schemaVersion must be maggie-video-playback-evidence.v1")
+    if not evidence.get("sourceRevision") or not evidence.get("jobId"): errors.append("jobId and sourceRevision are required")
+    viewports = evidence.get("viewports") if isinstance(evidence.get("viewports"), list) else []
+    required = {"desktop", "tablet", "mobile"}
+    if not required.issubset({item.get("viewport") for item in viewports if isinstance(item, dict)}): errors.append("desktop, tablet, and mobile playback evidence are required")
+    for item in viewports:
+        if not isinstance(item, dict) or item.get("status") != "passed": errors.append("every viewport playback check must pass")
+        if isinstance(item, dict) and not item.get("posterVisible"): errors.append("posterVisible is required for each viewport")
+    if evidence.get("rawProviderPayloadIncluded") is not False: errors.append("raw provider payloads must not be included")
+    return emit({"schemaVersion": "maggie-video-playback-evidence.v1", "passed": not errors, "jobId": evidence.get("jobId"), "viewports": [item.get("viewport") for item in viewports if isinstance(item, dict)], "errors": errors, "rawProviderPayloadIncluded": False}, args.output)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie workflows")
+    sub = parser.add_subparsers(dest="command", required=True)
+    media = sub.add_parser("media"); media_sub = media.add_subparsers(dest="media_command", required=True)
+    for kind, relative in (("image", "maggie-media/image-generation-policy-v1.json"), ("video", "maggie-media/video-generation-policy-v1.json")):
+        command = media_sub.add_parser(f"{kind}-policy"); command.add_argument("--policy", default=str(contract_root() / relative)); command.add_argument("--output"); command.set_defaults(func=validate_media, kind=kind)
+    job = media_sub.add_parser("video-job"); job.add_argument("--job", required=True); job.add_argument("--output"); job.set_defaults(func=validate_video_job)
+    video_provider = media_sub.add_parser("video-provider-evidence"); video_provider.add_argument("--evidence", required=True); video_provider.add_argument("--environment", choices=["test", "staging", "production"]); video_provider.add_argument("--model"); video_provider.add_argument("--require-host", action="store_true"); video_provider.add_argument("--output"); video_provider.set_defaults(func=validate_video_provider_evidence)
+    provenance = sub.add_parser("provenance"); provenance.add_argument("--project", default="."); provenance.add_argument("--source"); provenance.add_argument("--boundary", choices=["git-source", "host-runtime", "generated-artifact"], default="git-source"); provenance.add_argument("--output"); provenance.set_defaults(func=capture_provenance)
+    scaffold_parser = sub.add_parser("scaffold"); scaffold_parser.add_argument("--project", default="."); scaffold_parser.add_argument("--framework", choices=sorted(FRAMEWORK_PACKAGES), required=True); scaffold_parser.add_argument("--language", choices=["typescript", "javascript"], default="typescript"); scaffold_parser.add_argument("--package-manager", choices=["npm", "pnpm", "yarn", "bun"], default="npm"); scaffold_parser.add_argument("--install-dependencies", action="store_true"); scaffold_parser.add_argument("--write", action="store_true"); scaffold_parser.add_argument("--confirm", action="store_true"); scaffold_parser.add_argument("--force", action="store_true"); scaffold_parser.add_argument("--output"); scaffold_parser.set_defaults(func=scaffold)
+    brand = sub.add_parser("brand-kit"); brand.add_argument("--manifest"); brand.add_argument("--project", default="."); brand.add_argument("--design"); brand.add_argument("--tokens"); brand.add_argument("--logo"); brand.add_argument("--font"); brand.add_argument("--icon-library", default="host-icon-library"); brand.add_argument("--assets"); brand.add_argument("--write", action="store_true"); brand.add_argument("--confirm", action="store_true"); brand.add_argument("--output"); brand.set_defaults(func=lambda args: validate_brand(args) if args.manifest else brand_kit(args))
+    npm = sub.add_parser("npm11"); npm.add_argument("--project", default="."); npm.add_argument("--smoke", action="store_true"); npm.add_argument("--confirm", action="store_true"); npm.add_argument("--output"); npm.set_defaults(func=npm11)
+    booking = sub.add_parser("booking-delivery"); booking.add_argument("--policy", default=str(contract_root() / "maggie-service-booking/delivery-provider-default-v1.json")); booking.add_argument("--output"); booking.set_defaults(func=validate_booking_delivery)
+    playback = sub.add_parser("video-playback"); playback.add_argument("--evidence", required=True); playback.add_argument("--output"); playback.set_defaults(func=validate_playback)
+    args = parser.parse_args()
+    try:
+        return args.func(args)
+    except (OSError, ValueError, json.JSONDecodeError, subprocess.CalledProcessError) as error:
+        print(f"BLOCKED: maggie workflow: {error}", file=__import__("sys").stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/site_audit.py

@@ -8,6 +8,7 @@ import hashlib
 import json
 import re
 import sys
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from urllib.parse import urljoin, urlparse, urlunparse
 from html.parser import HTMLParser
@@ -176,6 +177,20 @@ def fetch(url: str, evidence: dict | None = None) -> tuple[int, str, str]:
         return response.status, response.headers.get_content_type(), body
 
 
+def indexability_if_indexed(page: PageParser, robots: list[str]) -> dict:
+    """Explain what a noindex page would fail if it became indexable."""
+    tokens = [token.strip().rsplit(":", 1)[-1] for directive in robots for token in directive.split(",")]
+    blocked = sorted(set(tokens) & {"noindex", "none"})
+    checks = {
+        "title": bool(page.title),
+        "description": bool(page.meta.get("description")),
+        "canonical": bool(page.canonical) and urlparse(page.canonical).fragment == "",
+        "headings": bool(page.headings) and page.h1 == 1,
+        "jsonld": page.jsonld > 0 and all(item is not None for item in page.jsonld_values),
+    }
+    return {"applicable": bool(blocked), "blockedBy": blocked, "wouldPass": all(checks.values()) if blocked else None, "checks": checks if blocked else {}}
+
+
 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)
@@ -184,6 +199,7 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
     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]
+    hypothetical = indexability_if_indexed(page, robots)
     return {
         "url": url,
         "status": status,
@@ -236,6 +252,7 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
         "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,
         "primary_navigation_links": page.primary_navigation_links,
+        "indexabilityIfIndexed": hypothetical,
     }
 
 
@@ -448,6 +465,12 @@ def parse_baseline_reasons(values: list[str], drift_urls: set[str], reason_all:
     return reasons
 
 
+def baseline_ack_expiry(days: int) -> str:
+    if not 1 <= days <= 3650:
+        raise ValueError("baseline acknowledgement TTL must be between 1 and 3650 days")
+    return (datetime.now(timezone.utc) + timedelta(days=days)).isoformat().replace("+00:00", "Z")
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("url")
@@ -471,6 +494,7 @@ def main() -> int:
     parser.add_argument("--baseline-id", help="required stable ID for --recapture-baseline")
     parser.add_argument("--reason", action="append", default=[], metavar="URL=REASON", help="reviewer-approved reason for one drifting URL; repeat for every drift")
     parser.add_argument("--reason-all", help="reviewer-approved reason applied to every drifting URL during baseline recapture")
+    parser.add_argument("--reason-ttl-days", type=int, default=30, help="expiry for a reviewed baseline drift acknowledgement (default: 30)")
     parser.add_argument("--reviewer", help="required for --save-baseline")
     args = parser.parse_args()
     if args.max_pages < 1:
@@ -503,7 +527,8 @@ def main() -> int:
     base = args.url.rstrip("/")
     checks = {}
     try:
-        status, content_type, html = fetch(base)
+        homepage_response = {}
+        status, content_type, html = fetch(base, homepage_response)
         page = PageParser()
         page.feed(html)
         checks["homepage"] = {"ok": status == 200 and content_type == "text/html", "status": status, "content_type": content_type}
@@ -522,6 +547,7 @@ def main() -> int:
         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}
+        checks["indexability_if_indexed"] = {"ok": True, **indexability_if_indexed(page, page.robots_directives + [value.lower() for value in homepage_response.get("xRobotsTag", [])])}
         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:
@@ -614,6 +640,7 @@ def main() -> int:
                     baseline_id=args.baseline_id,
                     supersedes=previous_baseline.get("baselineId") or site_baseline.baseline_fingerprint(previous_baseline),
                     change_reasons=reasons,
+                    approval_expires_at=baseline_ack_expiry(args.reason_ttl_days),
                 )
                 site_baseline.save(args.recapture_baseline, recaptured)
                 result["baselineRecapture"] = {

package/bundled-tools/integrations/analytics.md

@@ -60,6 +60,20 @@ GSC data is read-only in this starter. Any query, page, or indexing report must
 show its date window and property so an agent does not confuse an empty result
 with a failed connection.
 
+The GSC readiness evidence contract is explicit and can be checked before the
+combined release gate:
+
+```bash
+maggie analytics gsc-readiness \
+  --gsc-evidence .maggie/gsc-readiness.json
+```
+
+The evidence must cover property/verification, canonical origin, robots,
+sitemap, read-only authorization, query/readback, and production smoke. Use
+`--gsc-evidence ... --require-gsc` with `maggie analytics release-gate` to make
+those checks blocking. The command does not authorize a property or mutate
+Search Console.
+
 Run the deterministic configuration gate before enabling production tracking:
 
 ```bash

package/bundled-tools/runtime/site_baseline.py

@@ -21,6 +21,7 @@ def snapshot(
     baseline_id: str | None = None,
     supersedes: str | None = None,
     change_reasons: dict[str, str] | None = None,
+    approval_expires_at: str | None = None,
 ) -> dict:
     if not reviewer.strip():
         raise ValueError("baseline requires a reviewer")
@@ -58,6 +59,8 @@ def snapshot(
         result["supersedes"] = supersedes
     if change_reasons:
         result["approvedChangeReasons"] = {key: change_reasons[key] for key in sorted(change_reasons)}
+    if approval_expires_at:
+        result["approval"] = {"type": "reviewed-drift-acknowledgement", "expiresAt": approval_expires_at}
     return result
 
 

package/package.json

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

package/references/browser-inspection.md

@@ -27,6 +27,27 @@ interaction states and triggers
 responsive differences
 ```
 
+Behavioral checks may be declared instead of hidden in a bespoke script. The
+manifest is safe to commit because input values are not copied into evidence:
+
+```json
+{
+  "schemaVersion": "maggie-browser-interactions.v1",
+  "steps": [
+    {"id": "open", "action": "click", "selector": "[data-menu]"},
+    {"id": "visible", "action": "assert-visible", "selector": "[data-drawer]"},
+    {"id": "styles", "action": "assert-style", "selector": "[data-drawer]", "property": "display", "value": "block"},
+    {"id": "privacy", "action": "assert-no-request", "origin": "third-party.example"}
+  ]
+}
+```
+
+Run it with `maggie browser-audit ... --interactions .maggie/interactions.json`.
+Supported actions cover click, fill, type, select, press, wait, visibility and
+state assertions, computed-style assertions, and new-request assertions. The
+browser adapter owns the session and the audit records only step IDs and
+redacted outcomes.
+
 If a target requires login, a bot challenge, a consent interaction, or a
 private browser profile, stop at that boundary and ask the user to provide
 authorized access. Do not bypass access controls or record cookies in project