@topy-ai/maggie 0.7.38 → 0.7.41

package/bundled-tools/clis/maggie_service_booking.py

@@ -222,7 +222,24 @@ def make_record(provider, source, pid, name, description, variants, booking, lin
     if not booking:
         for href,_ in links:
             if any(x in href.lower() for x in ("book","appointment","checkout")): booking=urljoin(source,href); break
-    return {"id":f"{provider}:{pid}","provider":provider,"providerServiceId":pid,"slug":slug(name),"title":name,"description":description.strip(),"sourceUrl":source,"category":{"level1":"Uncategorised","level2":None},"variants":variants,"bookingUrl":booking,"paymentUrl":None,"status":"active","supplyState":"live","displayState":"published","firstSeenAt":NOW(),"lastSeenAt":NOW()}
+    record = {"id":f"{provider}:{pid}","provider":provider,"providerServiceId":pid,"slug":slug(name),"title":name,"description":description.strip(),"sourceUrl":source,"category":{"level1":"Uncategorised","level2":None},"variants":variants,"bookingUrl":booking,"paymentUrl":None,"status":"active","supplyState":"live","displayState":"published","firstSeenAt":NOW(),"lastSeenAt":NOW()}
+    # A treatment is one catalogue entry. Duration/price choices belong to
+    # variants so the same treatment is not presented as four products.
+    durations = [int(item["durationMinutes"]) for item in variants if isinstance(item, dict) and isinstance(item.get("durationMinutes"), (int, float)) and item["durationMinutes"] > 0]
+    priced = [item.get("price", {}) for item in variants if isinstance(item, dict) and isinstance(item.get("price"), dict) and isinstance(item.get("price", {}).get("amountMinor"), int)]
+    currencies = {item.get("currency") for item in priced if item.get("currency")}
+    from_price = None
+    if priced and len(currencies) == 1:
+        lowest = min(priced, key=lambda item: item["amountMinor"])
+        from_price = {"amountMinor": lowest["amountMinor"], "currency": lowest["currency"]}
+    record["treatmentGroup"] = {
+        "id": record["id"],
+        "title": name,
+        "variantCount": len(variants),
+        "durationRange": {"minMinutes": min(durations), "maxMinutes": max(durations)} if durations else None,
+        "fromPrice": from_price,
+    }
+    return record
 
 def root(args): return Path(args.project).resolve()
 def path(project): return project/".maggie"/"booking"/"services.json"
@@ -1263,6 +1280,36 @@ def cmd_resolver_audit(args):
     print(json.dumps({"status": report["status"], "report": str(output), "counts": counts, "errors": errors}, indent=2)); return 0 if not errors else 1
 
 
+def cmd_treatment_group_audit(args):
+    """Require one treatment record with explicit duration/price variants."""
+    data = load(root(args))
+    errors = []
+    groups = {}
+    for service in data.get("services", []):
+        group = service.get("treatmentGroup") if isinstance(service.get("treatmentGroup"), dict) else {}
+        group_id = str(group.get("id") or "")
+        if not group_id:
+            errors.append(f"{service.get('id', 'unknown')}: missing treatmentGroup.id")
+            continue
+        if group_id in groups:
+            errors.append(f"duplicate treatment group: {group_id}")
+        groups[group_id] = service.get("id")
+        variants = service.get("variants") if isinstance(service.get("variants"), list) else []
+        if not variants:
+            errors.append(f"{service.get('id', 'unknown')}: treatment group has no variants")
+        if group.get("variantCount") != len(variants):
+            errors.append(f"{service.get('id', 'unknown')}: treatmentGroup.variantCount is stale")
+        durations = [item.get("durationMinutes") for item in variants if isinstance(item, dict) and isinstance(item.get("durationMinutes"), (int, float))]
+        duration_range = group.get("durationRange")
+        if durations and (not isinstance(duration_range, dict) or duration_range.get("minMinutes") != min(durations) or duration_range.get("maxMinutes") != max(durations)):
+            errors.append(f"{service.get('id', 'unknown')}: treatmentGroup.durationRange is stale")
+    report = {"schemaVersion": "maggie-treatment-groups.v1", "passed": not errors, "errors": errors, "treatments": len(groups), "variants": sum(len(item.get("variants", [])) for item in data.get("services", []))}
+    if args.output:
+        output = (root(args) / args.output).resolve() if not Path(args.output).is_absolute() else Path(args.output)
+        output.parent.mkdir(parents=True, exist_ok=True); output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
 def main():
     p=argparse.ArgumentParser(); sub=p.add_subparsers(dest="command",required=True)
     for name in ("import","sync","run"):
@@ -1279,6 +1326,7 @@ def main():
     q=sub.add_parser("category-hash"); q.add_argument("--project",default="."); q.add_argument("--copy-data",required=True); q.add_argument("--apply",action="store_true",help="backfill deterministic provenance hashes in this generated artifact")
     q=sub.add_parser("fact-audit"); q.add_argument("--project",default="."); q.add_argument("--backfill-source",action="store_true",help="copy the catalogue sourceUrl into records that have no sourceUrl"); q.add_argument("--overrides",help="JSON of human-approved, evidenced descriptions for provider gaps"); q.add_argument("--apply-overrides",action="store_true",help="apply only approved fact overrides to the draft catalogue")
     q=sub.add_parser("catalogue-check"); q.add_argument("source"); q.add_argument("--project",default="."); q.add_argument("--provider",default="fresha",choices=["fresha"]); q.add_argument("--treatment",action="append",required=True,help="provider treatment name; repeat for multiple checks")
+    q=sub.add_parser("treatment-group-audit", help="ensure each treatment is one entry with duration/price variants"); q.add_argument("--project",default="."); q.add_argument("--output")
     q=sub.add_parser("retirement-audit"); q.add_argument("--project",default="."); q.add_argument("--catalogue",default=".maggie/booking/services.json"); q.add_argument("--evidence",required=True,help="sanitized runtime retirement evidence JSON"); q.add_argument("--output",default="docs/service-retirement-audit.json")
     q=sub.add_parser("capability-audit", help="validate provider variant declarations and fixture evidence"); q.add_argument("--project",default="."); q.add_argument("--provider"); q.add_argument("--catalogue",default=".maggie/booking/services.json"); q.add_argument("--capabilities-file",default=".maggie/booking/provider-capabilities.json"); q.add_argument("--fixture",help="sanitized provider fixture JSON"); q.add_argument("--output")
     q=sub.add_parser("category-context"); q.add_argument("--project",default="."); q.add_argument("--output")
@@ -1306,6 +1354,7 @@ def main():
     if a.command=="category-hash": return cmd_category_hash(a)
     if a.command=="fact-audit": return cmd_fact_audit(a)
     if a.command=="catalogue-check": return cmd_catalogue_check(a)
+    if a.command=="treatment-group-audit": return cmd_treatment_group_audit(a)
     if a.command=="retirement-audit": return cmd_retirement_audit(a)
     if a.command=="capability-audit": return cmd_capability_audit(a)
     if a.command=="category-context": return cmd_category_context(a)

package/bundled-tools/clis/maggie_workflows.py

@@ -0,0 +1,387 @@
+#!/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 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)
+    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())