@topy-ai/maggie 0.6.0 → 0.6.2

package/README.md

@@ -70,6 +70,8 @@ maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
 maggie seo images ...             # inventory, variants, confirmation, validate
 maggie seo sitemap ...            # typed plan, validate, apply, rollback
 maggie deployment | migration | release | analytics | schedule
+maggie deployment canary --asset URL=SHA256 --render-report report.json
+maggie design icon-inventory --source-dir src --runtime assets/icons.css
 maggie api lifecycle | site-audit | ops audit
 ```
 
@@ -107,11 +109,34 @@ Read the [performance PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/mai
 and [image/sitemap PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/image-sitemap-structure-prd.md)
 for adapter, privacy, apply, rollback, and release gates.
 
+### Design and deployment release gates
+
+Check source-to-runtime icon coverage before shipping a design:
+
+```bash
+maggie design icon-inventory --project . --source-dir src \
+  --runtime public/assets/icons.css --output docs/icon-inventory.json
+```
+
+After deployment, compare an immutable asset fingerprint and validate the
+browser adapter's rendered report:
+
+```bash
+maggie deployment canary --project . \
+  --asset https://example.com/assets/app.abc123.js=<sha256> \
+  --render-report .maggie/rendered-canary.json \
+  --output docs/deployment-canary.json
+```
+
+The canary report requires a screenshot and zero console errors, missing
+assets, and visual placeholders for every route. It records safe cache headers
+only and never stores response bodies, cookies, or credentials.
+
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.6.0 update --project . --force
-npx @topy-ai/maggie@0.6.0 cleanup --project .
+npx @topy-ai/maggie@0.6.2 update --project . --force
+npx @topy-ai/maggie@0.6.2 cleanup --project .
 ```
 
 ## MaggieDash lifecycle

package/bin/maggie.js

@@ -88,6 +88,7 @@ Usage:
   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 icon-inventory --project PATH --source-dir src --runtime assets/icons.css --output docs/icon-inventory.json
   maggie design author --project PATH --route /about --purpose TEXT --audience TEXT --confirm
   maggie auth reference --project PATH --confirm
   maggie auth check --project PATH [--production]
@@ -102,6 +103,7 @@ Usage:
   maggie service convert-page <page-path> --project PATH
   maggie service match-pages --project PATH --pages-dir src/pages
   maggie deployment --project PATH --target vps-with-cloudflare-dns
+  maggie deployment canary --project PATH --asset URL=SHA256 --render-report report.json --output docs/deployment-canary.json
   maggie migration --project PATH --environment staging
   maggie schedule PATH/.maggie/schedule.json --project PATH
   maggie analytics --project PATH --environment staging
@@ -369,12 +371,14 @@ try {
   else if (command === "marketplace") marketplace(args);
   else if (command === "clone") workflowCli("maggie_clone.py", args);
   else if (command === "clone-to-template") workflowCli("maggie_clone_to_template.py", args);
+  else if (command === "design" && args[0] === "icon-inventory") workflowCli("maggie_icon_inventory.py", args.slice(1));
   else if (command === "design") workflowCli("maggie_design.py", args);
   else if (command === "auth") workflowCli("maggie_auth.py", args);
   else if (command === "blog") workflowCli("maggie_blog.py", args);
   else if (command === "service") service(args);
   else if (command === "seo") seo(args);
   else if (command === "ops") workflowCli("maggie_ops.py", args);
+  else if (command === "deployment" && args[0] === "canary") workflowCli("maggie_deployment_canary.py", args.slice(1));
   else if (command === "deployment") workflowCli("maggie_deployment.py", args);
   else if (command === "migration") workflowCli("maggie_migration.py", args);
   else if (command === "schedule") workflowCli("maggie_schedule.py", args);

package/bundled-contracts/maggie-deployment/canary-report-v1.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Maggie edge and rendered deployment canary",
+  "type": "object",
+  "required": ["schemaVersion", "assets", "status"],
+  "properties": {"schemaVersion": {"const": "maggie-deployment-canary.v1"}, "assets": {"type": "array"}, "rendered": {"type": ["object", "null"]}, "status": {"enum": ["pass", "fail"]}}
+}

package/bundled-contracts/maggie-design/icon-inventory-v1.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Maggie source-to-runtime icon inventory",
+  "type": "object",
+  "required": ["schemaVersion", "source", "runtime", "coverage", "missing", "status"],
+  "properties": {"schemaVersion": {"const": "maggie-icon-inventory.v1"}, "source": {"type": "object"}, "runtime": {"type": "object"}, "coverage": {"type": "object"}, "missing": {"type": "array", "items": {"type": "string"}}, "status": {"enum": ["pass", "fail"]}}
+}

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

@@ -2,11 +2,34 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Maggie Deployment
 
+## Edge and rendered canary
+
+After staging or production deployment, verify that the edge serves the
+expected immutable asset bytes and validate a browser-produced rendered report:
+
+```bash
+maggie deployment canary --project . \
+  --asset https://example.com/assets/app.abc123.js=<sha256> \
+  --render-report .maggie/rendered-canary.json \
+  --output docs/deployment-canary.json
+```
+
+The asset probe records only safe cache headers and compares the response
+SHA-256 with the supplied release fingerprint. The rendered report must have a
+`routes` array; every route needs a screenshot and zero `consoleErrors`,
+`missingAssets`, and `placeholderCount`. A browser adapter (for example
+Playwright in the host project) produces that report; Maggie validates it and
+never claims a static HTML fetch is a rendered browser check. The command is
+read-only and returns non-zero on stale bytes, missing screenshots, console
+errors, missing assets, or visual placeholders. The result follows
+`maggie-deployment-canary.v1`; never include cookies, authorization headers, or
+response bodies in it.
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

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

@@ -2,11 +2,30 @@
 name: maggie-design
 description: Design authorized interior pages, review rendered responsive layouts, or explicitly rebrand a packaged homepage/template. Use rebrand only with a named source brand and target brand.
 metadata:
-  version: 1.2.0
+  version: 1.3.0
 ---
 
 # Maggie Design
 
+## Source-to-runtime icon inventory
+
+Before release, inventory icon names in source and compare them with the
+runtime CSS/icon map (and any declared font files). The command is read-only
+apart from its explicit report path and fails when a source icon is missing:
+
+```bash
+maggie design icon-inventory --project . --source-dir src \
+  --runtime public/assets/icons.css --runtime public/assets/icons.woff2 \
+  --output docs/icon-inventory.json
+```
+
+Use `missing`, `unknown`, and `coverage` from the versioned
+`maggie-icon-inventory.v1` report as the release gate. A binary font without a
+name map is reported as evidence only; it must not be treated as proof that a
+glyph exists. Fix the source token or add the runtime definition before
+shipping. Do not paste private source, URLs with credentials, or user data
+into the report.
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

package/bundled-tools/clis/maggie_deployment_canary.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Verify edge asset fingerprints and a browser-produced rendered canary report."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def fetch_asset(url: str, expected_sha256: str | None) -> dict:
+    if urlparse(url).scheme not in {"http", "https"}:
+        raise ValueError("asset URL must use http or https")
+    request = urllib.request.Request(url, headers={"User-Agent": "maggie-deployment-canary/1.0"})
+    with urllib.request.urlopen(request, timeout=20) as response:
+        body = response.read(); headers = {key.lower(): value for key, value in response.headers.items()}
+        actual = hashlib.sha256(body).hexdigest()
+        return {"url": url, "status": response.status, "sha256": actual, "expectedSha256": expected_sha256, "match": expected_sha256 is None or actual == expected_sha256, "headers": {key: headers[key] for key in ("cache-control", "etag", "age", "cf-cache-status", "cf-ray", "x-cache", "content-type") if key in headers}}
+
+
+def validate_render_report(path: Path) -> tuple[bool, dict]:
+    report = json.loads(path.read_text(encoding="utf-8"))
+    routes = report.get("routes")
+    if not isinstance(routes, list) or not routes: raise ValueError("render report requires a non-empty routes array")
+    failures = []
+    for route in routes:
+        if route.get("consoleErrors") or route.get("missingAssets") or route.get("placeholderCount", 0): failures.append(route.get("route", "unknown"))
+        if not route.get("screenshot"): failures.append(f"{route.get('route', 'unknown')}:screenshot")
+    return not failures, {"path": str(path), "routeCount": len(routes), "failures": failures, "report": report}
+
+
+def canary(project: Path, asset: list[str], render_report: Path | None, output: Path | None) -> int:
+    assets = []
+    for item in asset:
+        if "=" in item: url, expected = item.split("=", 1)
+        else: url, expected = item, None
+        assets.append(fetch_asset(url, expected or None))
+    rendered = None
+    if render_report:
+        ok, rendered = validate_render_report(render_report.resolve())
+    else: ok = True
+    result = {"schemaVersion": "maggie-deployment-canary.v1", "workflow": "maggie-deployment", "project": str(project.resolve()), "assets": assets, "rendered": rendered, "status": "pass" if ok and all(a["match"] for a in assets) else "fail", "generatedAt": datetime.now(timezone.utc).isoformat()}
+    encoded = json.dumps(result, indent=2, ensure_ascii=False) + "\n"
+    if output: destination = (project / output).resolve() if not output.is_absolute() else output.resolve(); destination.parent.mkdir(parents=True, exist_ok=True); destination.write_text(encoded, encoding="utf-8"); result["output"] = str(destination); encoded = json.dumps(result, indent=2, ensure_ascii=False) + "\n"
+    print(encoded, end=""); return 0 if result["status"] == "pass" else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__); parser.add_argument("--project", type=Path, default=Path.cwd()); parser.add_argument("--asset", action="append", default=[], help="URL or URL=expected-sha256; repeatable"); parser.add_argument("--render-report", type=Path); parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    try: return canary(args.project, args.asset, args.render_report, args.output)
+    except (OSError, ValueError, urllib.error.URLError, json.JSONDecodeError) as error: print(f"BLOCKED: maggie-deployment canary: {error}", file=__import__("sys").stderr); return 2
+
+
+if __name__ == "__main__": raise SystemExit(main())

package/bundled-tools/clis/maggie_icon_inventory.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Inventory source icon names and compare them with runtime CSS/font maps."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+SOURCE_EXTENSIONS = {".astro", ".css", ".html", ".jsx", ".js", ".json", ".svelte", ".tsx", ".ts", ".vue"}
+IGNORE_NAMES = {"icon", "icons", "true", "false", "null", "undefined"}
+
+
+def _add(found: dict[str, set[str]], name: str, file: Path, evidence: str) -> None:
+    name = name.strip().lower()
+    if not name or name in IGNORE_NAMES or len(name) > 80 or not re.fullmatch(r"[a-z0-9][a-z0-9._:/-]*", name):
+        return
+    found.setdefault(name, set()).add(f"{file.as_posix()}:{evidence}")
+
+
+def source_icons(root: Path, source_dir: Path) -> dict[str, set[str]]:
+    found: dict[str, set[str]] = {}
+    base = source_dir.resolve()
+    for file in sorted(base.rglob("*")):
+        if not file.is_file() or file.suffix.lower() not in SOURCE_EXTENSIONS:
+            continue
+        text = file.read_text(encoding="utf-8", errors="replace")
+        relative = file.relative_to(root.resolve())
+        for match in re.finditer(r"(?:icon|glyph|symbol)\s*[:=]\s*[\"']([^\"']+)", text, re.I):
+            _add(found, match.group(1), relative, "named-property")
+        for match in re.finditer(r"data-(?:icon|glyph)\s*=\s*[\"']([^\"']+)", text, re.I):
+            _add(found, match.group(1), relative, "data-attribute")
+        for match in re.finditer(r"(?:ph|fa|lucide|icon)-([a-z0-9][a-z0-9-]*)", text, re.I):
+            _add(found, match.group(1), relative, "icon-class")
+        for match in re.finditer(r"(?:phosphor|lucide|icon)[:/]([a-z0-9][a-z0-9-]*)", text, re.I):
+            _add(found, match.group(1), relative, "icon-token")
+    return found
+
+
+def runtime_icons(root: Path, runtime_paths: list[Path]) -> tuple[set[str], dict[str, set[str]], list[str]]:
+    names: set[str] = set(); evidence: dict[str, set[str]] = {}; font_files: list[str] = []
+    for path in runtime_paths:
+        path = path.resolve()
+        if not path.exists():
+            continue
+        if path.suffix.lower() in {".woff", ".woff2", ".ttf", ".otf"}:
+            font_files.append(str(path.relative_to(root.resolve())) if path.is_relative_to(root.resolve()) else str(path))
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        relative = path.relative_to(root.resolve()) if path.is_relative_to(root.resolve()) else path
+        for match in re.finditer(r"\.(?:ph|fa|lucide|icon)-([a-z0-9][a-z0-9-]*)\b", text, re.I):
+            name = match.group(1).lower(); names.add(name); evidence.setdefault(name, set()).add(f"{relative}:css-class")
+        for match in re.finditer(r"(?:data-(?:icon|glyph)|icon)\s*=\s*[\"']([^\"']+)", text, re.I):
+            name = match.group(1).lower(); names.add(name); evidence.setdefault(name, set()).add(f"{relative}:runtime-map")
+    return names, evidence, font_files
+
+
+def inventory(project: Path, source_dir: Path, runtime: list[Path], output: Path | None) -> int:
+    project = project.resolve(); source = (project / source_dir).resolve() if not source_dir.is_absolute() else source_dir.resolve()
+    if not source.is_dir(): raise ValueError(f"source directory not found: {source}")
+    runtime_paths = [((project / path) if not path.is_absolute() else path) for path in runtime]
+    sources = source_icons(project, source)
+    available, runtime_evidence, fonts = runtime_icons(project, runtime_paths)
+    source_names = sorted(sources); missing = sorted(set(source_names) - available); matched = sorted(set(source_names) & available)
+    report = {
+        "schemaVersion": "maggie-icon-inventory.v1", "workflow": "maggie-design",
+        "source": {"directory": str(source), "names": [{"name": n, "evidence": sorted(sources[n])} for n in source_names]},
+        "runtime": {"paths": [str(p) for p in runtime_paths], "names": [{"name": n, "evidence": sorted(runtime_evidence.get(n, []))} for n in sorted(available)], "fontFiles": fonts},
+        "coverage": {"sourceCount": len(source_names), "matchedCount": len(matched), "missingCount": len(missing), "ratio": round(len(matched) / len(source_names), 4) if source_names else 1.0},
+        "missing": missing, "unknown": [str(p) for p in runtime_paths if not p.exists()],
+        "status": "pass" if not missing and not any(not p.exists() for p in runtime_paths) else "fail",
+        "generatedAt": datetime.now(timezone.utc).isoformat(),
+    }
+    encoded = json.dumps(report, indent=2, ensure_ascii=False) + "\n"
+    if output:
+        destination = (project / output).resolve() if not output.is_absolute() else output.resolve(); destination.parent.mkdir(parents=True, exist_ok=True); destination.write_text(encoded, encoding="utf-8"); report["output"] = str(destination); encoded = json.dumps(report, indent=2, ensure_ascii=False) + "\n"
+    print(encoded, end="")
+    return 0 if report["status"] == "pass" else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=Path.cwd()); parser.add_argument("--source-dir", type=Path, default=Path("src")); parser.add_argument("--runtime", action="append", type=Path, required=True, help="CSS, icon map, or font file; repeatable"); parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    try: return inventory(args.project, args.source_dir, args.runtime, args.output)
+    except (OSError, ValueError, json.JSONDecodeError) as error: print(f"BLOCKED: maggie-design icon-inventory: {error}", file=__import__("sys").stderr); return 2
+
+
+if __name__ == "__main__": raise SystemExit(main())

package/bundled-tools/clis/maggie_memory.py

@@ -20,19 +20,25 @@ def main() -> int:
     parser = argparse.ArgumentParser(prog="maggie memory", description=__doc__)
     parser.add_argument("--project", default=".")
     sub = parser.add_subparsers(dest="command", required=True)
-    sub.add_parser("init")
-    listing = sub.add_parser("list")
+    def add_project(command: argparse.ArgumentParser) -> argparse.ArgumentParser:
+        # SUPPRESS preserves a global --project supplied before the command
+        # while also accepting the documented, conventional position after it.
+        command.add_argument("--project", default=argparse.SUPPRESS)
+        return command
+
+    add_project(sub.add_parser("init"))
+    listing = add_project(sub.add_parser("list"))
     listing.add_argument("--kind", choices=sorted(memory.KINDS), default=None)
     listing.add_argument("--status", choices=sorted(memory.STATUSES), default=None)
     listing.add_argument("--skill", default="")
     listing.add_argument("--query", default="")
-    search = sub.add_parser("search")
+    search = add_project(sub.add_parser("search"))
     search.add_argument("query")
     search.add_argument("--skill", default="")
-    context = sub.add_parser("context")
+    context = add_project(sub.add_parser("context"))
     context.add_argument("--skill", default="")
     context.add_argument("--query", default="")
-    add = sub.add_parser("add")
+    add = add_project(sub.add_parser("add"))
     add.add_argument("kind", choices=("preferences", "conventions", "lessons"))
     add.add_argument("--scope", choices=sorted(memory.SCOPES), required=True)
     add.add_argument("--type", dest="item_type", required=True)
@@ -48,7 +54,7 @@ def main() -> int:
     add.add_argument("--status", choices=sorted(memory.STATUSES), default="candidate")
     add.add_argument("--expires-at", default="")
     add.add_argument("--supersedes", default="")
-    error = sub.add_parser("record-error")
+    error = add_project(sub.add_parser("record-error"))
     error.add_argument("--skill", required=True)
     error.add_argument("--message", required=True)
     error.add_argument("--fingerprint", default="")
@@ -57,11 +63,11 @@ def main() -> int:
     error.add_argument("--validation", default="")
     error.add_argument("--fixed", action="store_true")
     error.add_argument("--trigger", action="append", default=[])
-    transition = sub.add_parser("transition")
+    transition = add_project(sub.add_parser("transition"))
     transition.add_argument("kind", choices=sorted(memory.KINDS))
     transition.add_argument("item_id")
     transition.add_argument("status", choices=sorted(memory.STATUSES))
-    export = sub.add_parser("export")
+    export = add_project(sub.add_parser("export"))
     export.add_argument("--output", required=True)
     export.add_argument("--public-safe", action="store_true")
     args = parser.parse_args()

package/package.json

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