@topy-ai/maggie 0.6.1 → 0.6.3

package/README.md

@@ -1,5 +1,7 @@
 # @topy-ai/maggie
 
+**Language:** English · [繁體中文](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
+
 [![npm version](https://img.shields.io/npm/v/@topy-ai/maggie)](https://www.npmjs.com/package/@topy-ai/maggie)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/LICENSE)
 
@@ -48,6 +50,26 @@ Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
 package ships 18 installable skills and a local-first MaggieDash foundation.
 
+For a genuinely empty project, create the host framework first, then bootstrap
+Maggie in this order:
+
+```bash
+python3 tools/clis/maggie.py analyze . --json --save
+python3 tools/clis/maggie.py bootstrap interview .
+python3 tools/clis/maggie_dash.py init --project . --confirm
+python3 tools/clis/maggie_dash.py migrate --project . --confirm
+```
+
+The normal daily loop is:
+
+```text
+doctor → memory context → inspect/plan → confirm → implement → test
+→ visual/SEO review → deploy staging → canary → publish with approval
+```
+
+Use `maggie memory record-error` for a repaired, reusable pitfall. Feedback is
+redacted and explicit; it is never promoted to active memory automatically.
+
 ## Command surface
 
 The CLI provides the installer plus durable workflow commands:
@@ -70,6 +92,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 +131,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.1 update --project . --force
-npx @topy-ai/maggie@0.6.1 cleanup --project .
+npx @topy-ai/maggie@0.6.2 update --project . --force
+npx @topy-ai/maggie@0.6.2 cleanup --project .
 ```
 
 ## MaggieDash lifecycle

package/README.zh-TW.md

@@ -0,0 +1,42 @@
+# @topy-ai/maggie（繁體中文）
+
+[English README](README.md) · [完整繁體中文 README](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
+
+`@topy-ai/maggie` 提供 18 個可安裝的 AI website workflow skills，支援
+Codex、Claude Code 與相容的 coding agents。
+
+## 安裝
+
+```bash
+npx @topy-ai/maggie@0.6.2 init --agent all
+npx @topy-ai/maggie doctor --project .
+```
+
+常用流程：
+
+```bash
+python3 tools/clis/maggie.py analyze . --json --save
+python3 tools/clis/maggie.py bootstrap interview .
+maggie memory context --project . --skill <skill-name>
+maggie doctor --project . --require-bootstrap --strict
+```
+
+主要 skills 包括 clone、design、template、Blog、SEO/GEO、localization、
+deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
+publish 與 production deployment 需要明確確認。
+
+新版 release gates：
+
+```bash
+maggie design icon-inventory --project . --source-dir src \
+  --runtime public/assets/icons.css --output docs/icon-inventory.json
+
+maggie deployment canary --project . \
+  --asset https://example.com/assets/app.js=<sha256> \
+  --render-report .maggie/rendered-canary.json \
+  --output docs/deployment-canary.json
+```
+
+完整中文說明、18 個 skills 清單和 roadmap：
+[繁體中文 README](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
+· [Roadmap](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/ROADMAP.md)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,7 @@
     "maggie": "bin/maggie.js"
   },
   "files": [
+    "README.zh-TW.md",
     "bin",
     "references",
     "bundled-skills",