@topy-ai/maggie 0.3.0 → 0.5.0

package/README.md

@@ -267,6 +267,24 @@ python3 tools/clis/maggie_design.py rebrand \
 | `maggie-auth-reference` | Generate and validate traditional email/password auth with secure server-side sessions |
 | `maggie-blog` | Run a provider-neutral blog lifecycle with stable identity, topics, feeds, settings, and rollback |
 
+`maggie-design` can initialize native blog and service UI plans from a local,
+read-only structural reference:
+
+```bash
+maggie design reference-ui --project . --reference /path/to/reference \
+  --surface blog,service --confirm
+maggie design init --project . --surface blog \
+  --reference-run .maggie/design/content-ui/reference-<id> --confirm
+maggie design init --project . --surface service \
+  --reference-run .maggie/design/content-ui/reference-<id> --confirm
+maggie design validate-ui --project . \
+  --plan .maggie/design/content-ui/blog/init-<id>/plan.json \
+  --rendered-dir .maggie/design/content-ui/blog/init-<id>/screenshots --confirm
+```
+
+This reuses the host project's homepage shell and `DESIGN.md`; it does not
+copy reference branding, source code, private data, or provider facts.
+
 The remaining installable skills are `maggie-blog-bootstrap`, `maggie-dash`,
 `maggie-clone`, `maggie-clone-to-template`, `maggie-marketplace`,
 `maggie-template`, `maggie-design`, `maggie-ops`, `maggie-deployment`,

package/bin/maggie.js

@@ -85,6 +85,9 @@ Usage:
   maggie clone run <homepage-url> --run-id <id>
   maggie clone status --run-id <id>
   maggie design run <target-url> --clone-run <id>
+  maggie design reference-ui --project PATH --reference PATH --surface blog,service --confirm
+  maggie design init --project PATH --surface blog|service --reference-run PATH --confirm
+  maggie design validate-ui --project PATH --plan PATH --rendered-dir PATH --confirm
   maggie design author --project PATH --route /about --purpose TEXT --audience TEXT --confirm
   maggie auth reference --project PATH --confirm
   maggie auth check --project PATH [--production]

package/bundled-contracts/maggie-content-ui/README.md

@@ -0,0 +1,6 @@
+# Maggie Content UI Contracts
+
+These contracts describe sanitized structural evidence captured from a local
+UI reference and the native implementation plan consumed by `maggie-design`.
+They intentionally exclude source-brand content, private data, credentials,
+raw assets, and copied source code.

package/bundled-contracts/maggie-content-ui/plan-v1.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "maggie-content-ui-plan.v1",
+  "type": "object",
+  "required": ["schemaVersion", "id", "workflow", "mode", "surface", "phase", "shell", "components", "routes", "dataAdapter", "publicWrite"],
+  "properties": {
+    "schemaVersion": { "const": "maggie-content-ui-plan.v1" },
+    "id": { "type": "string", "pattern": "^init-[a-f0-9]+$" },
+    "workflow": { "const": "maggie-design" },
+    "mode": { "const": "content-ui-init" },
+    "surface": { "enum": ["blog", "service"] },
+    "phase": { "const": "ready" },
+    "shell": { "type": "object", "required": ["sourceOfTruth", "reuse", "replaceAllowed"] },
+    "components": { "type": "array", "minItems": 1 },
+    "routes": { "type": "array", "minItems": 1 },
+    "dataAdapter": { "enum": ["maggie-blog", "maggie-service-booking"] },
+    "publicWrite": { "const": false }
+  }
+}

package/bundled-contracts/maggie-content-ui/reference-manifest-v1.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "maggie-content-ui-reference.v1",
+  "type": "object",
+  "required": ["schemaVersion", "id", "workflow", "mode", "surfaces", "sourcePolicy", "privateSourceCopied"],
+  "properties": {
+    "schemaVersion": { "const": "maggie-content-ui-reference.v1" },
+    "id": { "type": "string", "pattern": "^reference-[a-f0-9]+$" },
+    "workflow": { "const": "maggie-design" },
+    "mode": { "const": "reference-ui" },
+    "surfaces": { "type": "object", "minProperties": 1 },
+    "sourcePolicy": { "const": "read-only-structural-guideline" },
+    "privateSourceCopied": { "const": false }
+  }
+}

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

@@ -32,3 +32,15 @@ published slug must not change during a rewrite. Search/sort views are not
 indexable; drafts never appear in public routes, RSS, or sitemap output.
 Provider keys remain server-side. Public publication and migrations always
 require explicit confirmation.
+
+To initialize native front-end pages from the approved local UI guideline,
+run `maggie-design`:
+
+```bash
+maggie design init --project . --surface blog \
+  --reference-run .maggie/design/content-ui/reference-<id> \
+  --base-path /our-blogs --confirm
+```
+
+The blog skill supplies route/data semantics; `maggie-design` supplies the
+host-native components and responsive visual review.

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

@@ -90,6 +90,57 @@ unconfirmed writes. Generated copy and media must be marked authored rather
 than source-observed. Implementation must still capture responsive screenshots
 and run accessibility/build validation before publication.
 
+## Content UI initialization
+
+Use content UI initialization when `maggie-blog` or
+`maggie-service-booking` needs native front-end layouts based on a local UI
+reference. The reference is structural evidence only. It must not replace the
+project's `DESIGN.md`, homepage shell, brand, copy, assets, or provider facts.
+
+First record a sanitized, read-only reference manifest:
+
+```bash
+maggie design reference-ui \
+  --project . \
+  --reference /home/balalior/Dev/clients/spachevychase.org \
+  --surface blog,service --confirm
+```
+
+Then initialize one surface at a time from that manifest:
+
+```bash
+maggie design init --project . --surface blog \
+  --reference-run .maggie/design/content-ui/reference-<id> \
+  --base-path /our-blogs --confirm
+
+maggie design init --project . --surface service \
+  --reference-run .maggie/design/content-ui/reference-<id> \
+  --route-pattern '/services/[slug]/' --confirm
+```
+
+The initializer creates a reviewable component/route/responsive/provenance
+plan under `.maggie/design/content-ui/`. It does not write public components
+or publish routes. The implementation phase must call the matching data skill,
+reuse the homepage shell, capture desktop/tablet/mobile screenshots, and pass
+accessibility, metadata, build, and visual review gates before approval.
+
+Validate the rendered plan before approval:
+
+```bash
+maggie design validate-ui --project . \
+  --plan .maggie/design/content-ui/blog/init-<id>/plan.json \
+  --rendered-dir .maggie/design/content-ui/blog/init-<id>/screenshots \
+  --confirm
+```
+
+This gate requires valid PNG evidence for desktop, tablet, and mobile and keeps
+`publicWrite: false` until a separate approval step.
+
+For blog UI, preserve archive, topic, post/slug, pagination, RSS, and sitemap
+semantics from `maggie-blog`. For service UI, preserve provider identity,
+variants, booking URLs, duplicate canonical/noindex decisions, and service
+sitemap semantics from `maggie-service-booking`.
+
 ## Explicit homepage rebrand mode
 
 The homepage `review` mode only compares screenshots. It does not rebrand a

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -207,6 +207,19 @@ and `DESIGN.md`. Use the homepage header, footer, fonts, tokens, navigation,
 analytics boundary, accessibility behaviour, and responsive breakpoints.
 Only the service content region varies.
 
+When initializing a new service UI from the approved reference guideline, use
+the shared `maggie-design` initializer:
+
+```bash
+maggie design init --project . --surface service \
+  --reference-run .maggie/design/content-ui/reference-<id> \
+  --route-pattern '/services/[slug]/' --confirm
+```
+
+This creates a reviewable native component/route plan. It does not copy the
+reference project's brand, source code, assets, or provider facts, and it does
+not publish service pages without the existing service fact/copy gates.
+
 Each service page must expose the service title, category breadcrumbs, factual
 description, all active variants, duration, currency-formatted price, booking
 CTA, and payment CTA only if available. Preserve the provider booking URL as

package/bundled-tools/clis/maggie_design.py

@@ -34,6 +34,32 @@ DESIGN_HEADINGS = (
 
 REVIEW_VIEWPORTS = {"desktop": (1440, 900), "tablet": (768, 900), "mobile": (390, 844)}
 
+REFERENCE_SURFACES = {
+    "blog": {
+        "files": [
+            "src/layouts/BlogLayout.astro", "src/components/blog/BlogArchive.astro",
+            "src/components/blog/PostCard.astro", "src/components/blog/Pagination.astro",
+            "src/components/blog/PostSidebar.astro", "src/pages/our-blogs/index.astro",
+            "src/pages/our-blogs/[slug].astro", "src/pages/our-blogs/topic/[slug].astro",
+            "src/pages/rss.xml.ts", "src/pages/sitemap.xml.ts",
+        ],
+        "components": ["BlogLayout", "BlogArchive", "PostCard", "Pagination", "PostSidebar", "ShareMenu"],
+        "routes": ["{base}/", "{base}/page/{n}/", "{base}/{slug}/", "{base}/topic/{slug}/", "{base}/topic/{slug}/page/{n}/", "/rss.xml", "/sitemap.xml"],
+        "patterns": ["compact image-backed archive hero", "URL-backed search/topic/sort controls", "responsive post grid", "sticky article sidebar", "related articles", "crawlable topic links"],
+    },
+    "service": {
+        "files": [
+            "src/pages/services/index.astro", "src/pages/services/[slug].astro",
+            "src/components/ServicePage.astro", "src/components/CategoryServiceHub.astro",
+            "src/components/SupportingServicePage.astro", "src/components/ServiceContextNarrative.astro",
+            "src/pages/sitemap-services.xml.ts", "src/pages/sitemap-service-categories.xml.ts",
+        ],
+        "components": ["ServiceIndex", "CategoryServiceHub", "ServicePage", "ServiceFacts", "RelatedServices", "ServiceFaq"],
+        "routes": ["/services/", "/services/{slug}/", "/service-categories/{slug}/", "/sitemap-services.xml", "/sitemap-service-categories.xml"],
+        "patterns": ["category breadcrumb hero", "variant facts and booking card", "service narrative with image", "related treatment grid", "FAQ accordion", "category navigation"],
+    },
+}
+
 
 def rendered_asset_preflight(template: Path) -> list[str]:
     """Catch package CSS failures before visual comparison is trusted."""
@@ -56,6 +82,81 @@ def rendered_asset_preflight(template: Path) -> list[str]:
     return errors
 
 
+def _surface_list(value: str) -> list[str]:
+    surfaces = [item.strip().lower() for item in value.split(",") if item.strip()]
+    invalid = sorted(set(surfaces) - set(REFERENCE_SURFACES))
+    if invalid or not surfaces:
+        raise ValueError("surface must contain blog and/or service")
+    return list(dict.fromkeys(surfaces))
+
+
+def reference_ui(project: Path, reference: Path, surfaces: list[str], screenshots_dir: Path | None, confirm: bool) -> int:
+    """Record sanitized structural evidence from a read-only reference project."""
+    project = project.resolve(); reference = reference.resolve()
+    if not reference.is_dir(): raise ValueError(f"reference project not found: {reference}")
+    if not confirm: print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
+    missing = {surface: [item for item in REFERENCE_SURFACES[surface]["files"] if not (reference / item).exists()] for surface in surfaces}
+    missing = {key: value for key, value in missing.items() if value}
+    if missing: raise ValueError("reference files missing: " + json.dumps(missing, ensure_ascii=False))
+    digest = hashlib.sha256((str(reference) + "\n" + ",".join(surfaces)).encode()).hexdigest()[:12]
+    output_dir = project / ".maggie" / "design" / "content-ui" / f"reference-{digest}"; output_dir.mkdir(parents=True, exist_ok=True)
+    evidence = {}
+    for surface in surfaces:
+        config = REFERENCE_SURFACES[surface]
+        evidence[surface] = {"sourceFiles": config["files"], "components": config["components"], "routes": config["routes"], "patterns": config["patterns"], "observations": {pattern: True for pattern in config["patterns"]}}
+    screenshots = {name: "pending" for name in REVIEW_VIEWPORTS}
+    if screenshots_dir:
+        screenshots = {name: str((screenshots_dir / f"{name}.png").resolve()) if (screenshots_dir / f"{name}.png").is_file() else "missing" for name in REVIEW_VIEWPORTS}
+    manifest = {"schemaVersion": "maggie-content-ui-reference.v1", "id": f"reference-{digest}", "workflow": "maggie-design", "mode": "reference-ui", "referenceProject": reference.name, "surfaces": evidence, "screenshots": screenshots, "sourcePolicy": "read-only-structural-guideline", "privateSourceCopied": False, "createdAt": datetime.now(timezone.utc).isoformat()}
+    path = output_dir / "reference-manifest.json"; path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"manifest": str(path), "id": manifest["id"], "surfaces": surfaces, "screenshotStatus": screenshots}, indent=2, ensure_ascii=False)); return 0
+
+
+def init_content_ui(project: Path, surface: str, reference_run: Path, base_path: str, route_pattern: str, confirm: bool) -> int:
+    """Create the reviewable plan that Maggie Design will implement natively."""
+    project = project.resolve(); surface = surface.strip().lower()
+    if surface not in REFERENCE_SURFACES: raise ValueError("surface must be blog or service")
+    if not confirm: print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
+    contract = require_design_contract(project)
+    manifest_path = reference_run.resolve()
+    if manifest_path.is_dir(): manifest_path /= "reference-manifest.json"
+    if not manifest_path.exists(): raise ValueError(f"reference manifest required: {manifest_path}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if surface not in manifest.get("surfaces", {}): raise ValueError(f"reference manifest does not contain surface: {surface}")
+    digest = hashlib.sha256((str(project) + "\n" + surface + "\n" + str(manifest_path)).encode()).hexdigest()[:12]
+    output_dir = project / ".maggie" / "design" / "content-ui" / surface / f"init-{digest}"; output_dir.mkdir(parents=True, exist_ok=True)
+    config = REFERENCE_SURFACES[surface]
+    routes = config["routes"]
+    if surface == "blog": routes = [route.replace("{base}", base_path.rstrip("/") or "/our-blogs") for route in routes]
+    elif route_pattern: routes = [route_pattern, "/sitemap-services.xml", "/sitemap-service-categories.xml"]
+    plan = {"schemaVersion": "maggie-content-ui-plan.v1", "id": f"init-{digest}", "workflow": "maggie-design", "mode": "content-ui-init", "surface": surface, "phase": "ready", "referenceManifest": str(manifest_path), "designContract": contract, "shell": {"sourceOfTruth": "existing homepage shell", "reuse": ["header", "footer", "tokens", "typography", "icons", "breakpoints", "accessibility", "analytics"], "replaceAllowed": False}, "components": config["components"], "routes": routes, "dataAdapter": "maggie-blog" if surface == "blog" else "maggie-service-booking", "provenance": {"referenceObserved": True, "projectPreserved": True, "agentAuthored": True, "providerFact": surface == "service"}, "requiredSteps": ["inspect-host-shell", "create-native-components", "bind-data-adapter", "capture-desktop-tablet-mobile", "accessibility-check", "metadata-and-route-check", "build-check", "explicit-approval"], "publicWrite": False, "createdAt": datetime.now(timezone.utc).isoformat()}
+    files = {"reference-manifest.json": manifest, "shell-reuse.json": plan["shell"], "component-plan.json": {"components": config["components"], "patterns": config["patterns"]}, "route-plan.json": {"routes": routes, "dataAdapter": plan["dataAdapter"]}, "responsive-plan.json": {"viewports": REVIEW_VIEWPORTS, "mobileStickySidebar": False if surface == "blog" else None}, "provenance.json": plan["provenance"], "validation.json": {"status": "pending", "required": plan["requiredSteps"]}}
+    for filename, value in files.items(): (output_dir / filename).write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (output_dir / "screenshots").mkdir(exist_ok=True)
+    (output_dir / "plan.json").write_text(json.dumps(plan, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"plan": str(output_dir / "plan.json"), "surface": surface, "phase": "ready", "publicWrite": False}, indent=2)); return 0
+
+
+def validate_content_ui(project: Path, plan_path: Path, rendered_dir: Path | None, confirm: bool) -> int:
+    """Validate a generated content UI plan before host publication."""
+    project = project.resolve(); plan_path = plan_path.resolve()
+    if not plan_path.exists(): raise ValueError(f"content UI plan not found: {plan_path}")
+    plan = json.loads(plan_path.read_text(encoding="utf-8")); errors = []
+    if plan.get("workflow") != "maggie-design" or plan.get("mode") != "content-ui-init": errors.append("invalid design workflow plan")
+    if plan.get("publicWrite") is not False: errors.append("publicWrite must remain false before approval")
+    try: require_design_contract(project)
+    except ValueError as error: errors.append(str(error))
+    screenshot_status = {}
+    for name in REVIEW_VIEWPORTS:
+        path = (rendered_dir / f"{name}.png") if rendered_dir else plan_path.parent / "screenshots" / f"{name}.png"
+        valid = path.is_file() and path.read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
+        screenshot_status[name] = {"path": str(path), "validPng": valid}
+        if not valid: errors.append(f"missing valid {name} screenshot")
+    result = {"schemaVersion": "maggie-content-ui-validation.v1", "plan": str(plan_path), "surface": plan.get("surface"), "screenshots": screenshot_status, "checks": {"shellReuse": plan.get("shell", {}).get("replaceAllowed") is False, "publicWriteBlocked": plan.get("publicWrite") is False, "designContract": not any("DESIGN.md" in error for error in errors)}, "status": "passed" if not errors else "failed", "errors": errors, "validatedAt": datetime.now(timezone.utc).isoformat()}
+    if not confirm: print(json.dumps(result, indent=2, ensure_ascii=False)); return 0 if not errors else 1
+    output = plan_path.parent / "validation.json"; output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"); print(json.dumps(result, indent=2, ensure_ascii=False)); return 0 if not errors else 1
+
+
 def rebrand_template(args: argparse.Namespace) -> int:
     """Apply an explicit brand identity to a packaged homepage template."""
     template = args.template.resolve()
@@ -479,6 +580,42 @@ def author_job(project: Path, route: str, purpose: str, audience: str, brief_fil
 
 
 def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] == "reference-ui":
+        command = argparse.ArgumentParser(description="Record sanitized blog/service UI evidence from a read-only reference project.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--reference", type=Path, required=True)
+        command.add_argument("--surface", default="blog,service")
+        command.add_argument("--screenshots-dir", type=Path)
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return reference_ui(args.project, args.reference, _surface_list(args.surface), args.screenshots_dir, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design reference-ui: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "init":
+        command = argparse.ArgumentParser(description="Initialize a native blog or service UI plan from a sanitized reference manifest.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--surface", required=True, choices=["blog", "service"])
+        command.add_argument("--reference-run", type=Path, required=True)
+        command.add_argument("--base-path", default="/our-blogs")
+        command.add_argument("--route-pattern", default="/services/[slug]/")
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return init_content_ui(args.project, args.surface, args.reference_run, args.base_path, args.route_pattern, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design init: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "validate-ui":
+        command = argparse.ArgumentParser(description="Validate content UI screenshots and design/public-write gates.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--plan", type=Path, required=True)
+        command.add_argument("--rendered-dir", type=Path)
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return validate_content_ui(args.project, args.plan, args.rendered_dir, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design validate-ui: {error}", file=sys.stderr); return 1
     if len(sys.argv) > 1 and sys.argv[1] == "rebrand":
         rebrand = argparse.ArgumentParser(description="Apply an explicit brand identity to a packaged marketplace template.")
         rebrand.add_argument("--template", type=Path, required=True)

package/package.json

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