motion-ui-skill 2.0.0

package/scripts/install-component.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""
+Motion UI - Component Installer & Resolver
+Allows AI agents and developers to search, inspect, and install any catalogued
+animated UI component and its dependencies directly into any React/Next.js codebase.
+"""
+
+import os
+import sys
+import json
+import shutil
+import argparse
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parent.parent
+CATALOG_PATH = SKILL_ROOT / "catalog.json"
+
+def load_catalog():
+    if not CATALOG_PATH.exists():
+        print(f"Error: catalog.json not found at {CATALOG_PATH}", file=sys.stderr)
+        sys.exit(1)
+    with open(CATALOG_PATH, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+def list_components(catalog, category=None):
+    components = catalog.get("components", {})
+    categories = {c["slug"]: c["name"] for c in catalog.get("categories", [])}
+    
+    print(f"\n📦 Available Motion UI Components (Total: {len(components)})\n")
+    
+    grouped = {}
+    for slug, data in components.items():
+        cat = data.get("category", "other")
+        if category and cat != category:
+            continue
+        grouped.setdefault(cat, []).append(data)
+
+    for cat_slug in ["motion", "agents", "blocks", "craft"]:
+        if cat_slug not in grouped:
+            continue
+        items = grouped[cat_slug]
+        cat_title = categories.get(cat_slug, cat_slug.capitalize())
+        print(f"=== {cat_title} ({len(items)} components) ===")
+        for item in sorted(items, key=lambda x: x["name"]):
+            deps = ", ".join(item.get("dependencies", []))
+            print(f"  • {item['slug']:<26} {item['name']:<25} [{deps}]")
+        print()
+
+def search_components(catalog, query):
+    query = query.lower()
+    components = catalog.get("components", {})
+    matches = []
+    
+    for slug, data in components.items():
+        name = data.get("name", "").lower()
+        desc = data.get("description", "").lower()
+        cat = data.get("category", "").lower()
+        
+        if query in slug or query in name or query in desc or query in cat:
+            matches.append(data)
+            
+    if not matches:
+        print(f"No components found matching '{query}'.")
+        return
+        
+    print(f"\nFound {len(matches)} matching component(s):\n")
+    for item in matches:
+        print(f"• {item['name']} (`{item['slug']}`) [{item['category']}]")
+        print(f"  Description: {item['description']}")
+        print(f"  Dependencies: {', '.join(item.get('dependencies', []))}")
+        print(f"  Doc: {item.get('doc_path', 'N/A')}\n")
+
+def info_component(catalog, slug):
+    components = catalog.get("components", {})
+    if slug not in components:
+        print(f"Error: Component '{slug}' not found in catalog.", file=sys.stderr)
+        sys.exit(1)
+        
+    item = components[slug]
+    print(f"\n==========================================")
+    print(f"Component: {item['name']} ({item['slug']})")
+    print(f"Category:  {item['category']}")
+    print(f"Docs:      {item['doc_path']}")
+    print(f"==========================================")
+    print(f"\nDescription:\n  {item['description']}\n")
+    print(f"External Dependencies:\n  {', '.join(item.get('dependencies', []))}\n")
+    print("Component Files:")
+    for f in item.get("component_files", []):
+        print(f"  - {f}")
+    print("\nShared Utilities:")
+    for f in item.get("util_files", []):
+        print(f"  - {f}")
+    print()
+
+def safe_path(root, relative):
+    path = Path(relative)
+    root = root.resolve()
+    if path.is_absolute() or ".." in path.parts:
+        raise ValueError(f"Path must stay relative to {root}: {relative}")
+
+    candidate = root
+    for part in path.parts:
+        candidate /= part
+        if candidate.is_symlink():
+            raise ValueError(f"Symlinks are not allowed in install paths: {relative}")
+
+    target = candidate.resolve()
+    if target != root and root not in target.parents:
+        raise ValueError(f"Path escapes {root}: {relative}")
+
+    current = target
+    while current != root:
+        if current.is_symlink():
+            raise ValueError(f"Symlinks are not allowed in install paths: {relative}")
+        current = current.parent
+    return target
+
+
+def install_component(catalog, slug, dest_dir, include_previews=False, style=None):
+    components = catalog.get("components", {})
+    if slug not in components:
+        print(f"Error: Component '{slug}' not found in catalog.", file=sys.stderr)
+        sys.exit(1)
+        
+    item = components[slug]
+    dest = Path(dest_dir).resolve()
+    
+    files_to_copy = list(item.get("component_files", [])) + list(item.get("util_files", []))
+    if include_previews:
+        files_to_copy += list(item.get("preview_files", []))
+    if style:
+        files_to_copy += ["lib/styles.ts", "lib/ease.ts"]
+
+    print(f"🚀 Installing '{item['name']}' into: {dest}\n")
+    plan = []
+    errors = []
+    optional = set(item.get("preview_files", [])) if include_previews else set()
+    for rel_path in files_to_copy:
+        try:
+            src_file = safe_path(SKILL_ROOT, rel_path)
+            target_file = safe_path(dest, rel_path)
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+
+        if not src_file.is_file():
+            if rel_path in optional:
+                print(f"  ⚠️ Warning: Source file {src_file} missing, skipping.")
+            else:
+                errors.append(f"Required source file missing: {src_file}")
+            continue
+        plan.append((rel_path, src_file, target_file))
+
+    if errors:
+        for error in errors:
+            print(f"Error: {error}", file=sys.stderr)
+        sys.exit(1)
+
+    copied = 0
+    for rel_path, src_file, target_file in plan:
+        target_file.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src_file, target_file)
+        print(f"  ✓ Copied: {rel_path}")
+        copied += 1
+
+    print(f"\n✨ Successfully copied {copied} file(s) to {dest}!")
+    
+    # Check dependencies
+    deps = item.get("dependencies", [])
+    if deps:
+        deps_str = " ".join(deps)
+        print("\n📦 Required External Dependencies:")
+        print(f"   npm install {deps_str}")
+        print(f"   # or: pnpm add {deps_str}")
+        print(f"   # or: yarn add {deps_str}")
+        print(f"   # or: bun add {deps_str}")
+        
+    print(f"\n📖 Complete Guide & Examples: {item['doc_path']}\n")
+
+def list_styles():
+    styles = [
+        ("minimal", "Clean monochrome, flat surfaces, crisp 1px borders, subtle transitions (shadcn/ui style)"),
+        ("origin", "High-craft, micro-elevation, subtle specular inner borders, dark luxury (Coss / Cal.com style)"),
+        ("enterprise", "High information density, compact spacing, sharp geometry, data grids (KeenThemes ReUI style)"),
+        ("glow", "Luminous radial halos, spotlight cursor highlights, cyan/purple beams (ibelick style)"),
+        ("ios", "Fluid squircle curves, translucent blurred glass, bouncy springs, haptics (Expo / Apple style)"),
+        ("brutalist", "Bold 2px outlines, high-contrast flat fills, hard 4px offset drop-shadows (Neo-brutalist)"),
+    ]
+    print("\n🎨 Motion UI Aesthetic Style Presets:\n")
+    for name, desc in styles:
+        print(f"  • {name:<12} - {desc}")
+    print("\nUse `stylePreset='<name>'` on components that support it, or import tokens from `@/lib/styles`.\n")
+
+def main():
+    parser = argparse.ArgumentParser(description="Motion UI Component Resolver & Installer")
+    parser.add_argument("slug", nargs="?", help="Component slug to inspect or install")
+    parser.add_argument("--dest", "-d", default=".", help="Target destination directory (default: current directory)")
+    parser.add_argument("--list", "-l", action="store_true", help="List all available components")
+    parser.add_argument("--category", "-c", choices=["motion", "agents", "blocks"], help="Filter listing by category")
+    parser.add_argument("--search", "-s", help="Search components by keyword")
+    parser.add_argument("--info", "-i", action="store_true", help="Show detailed information about a component")
+    parser.add_argument("--with-previews", action="store_true", help="Also copy preview and demo files")
+    parser.add_argument("--style", choices=["minimal", "origin", "enterprise", "glow", "ios", "brutalist"], help="Also copy the shared style token helper for the selected preset")
+    parser.add_argument("--list-styles", action="store_true", help="List all available aesthetic style presets")
+
+    args = parser.parse_args()
+    catalog = load_catalog()
+
+    if args.list_styles:
+        list_styles()
+    elif args.list:
+        list_components(catalog, category=args.category)
+    elif args.search:
+        search_components(catalog, args.search)
+    elif args.slug:
+        if args.info:
+            info_component(catalog, args.slug)
+        else:
+            install_component(
+                catalog,
+                args.slug,
+                args.dest,
+                include_previews=args.with_previews,
+                style=args.style,
+            )
+            if args.style:
+                print(f"🎨 Included style preset tokens for '{args.style}'. Use stylePreset on supported components or getStylePreset() for custom wrappers.")
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

package/scripts/test_release.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Small dependency-free release checks for the skill package and installer."""
+
+import importlib.util
+import contextlib
+import io
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+INSTALLER = ROOT / "scripts" / "install-component.py"
+VERIFY = ROOT / "scripts" / "verify_skill.py"
+BUILD_DOCS = ROOT / "scripts" / "build_docs.py"
+
+
+def load_installer():
+    spec = importlib.util.spec_from_file_location("motion_ui_installer", INSTALLER)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def run_installer(*args):
+    return subprocess.run(
+        [sys.executable, str(INSTALLER), *args],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+    )
+
+
+def expect_exit_one(installer, catalog, slug, dest):
+    try:
+        installer.install_component(catalog, slug, dest)
+    except SystemExit as error:
+        if error.code == 1:
+            return
+    raise AssertionError("installer accepted an invalid catalog path")
+
+
+def main():
+    installer = load_installer()
+    with tempfile.TemporaryDirectory() as temp:
+        destination = Path(temp) / "install"
+        result = run_installer("resizable-panel", "--style", "glow", "--dest", str(destination))
+        if result.returncode != 0:
+            raise AssertionError(result.stderr)
+        for relative in (
+            "components/motion/resizable-panel.tsx",
+            "lib/styles.ts",
+            "lib/ease.ts",
+        ):
+            if not (destination / relative).is_file():
+                raise AssertionError(f"missing installed file: {relative}")
+        if "Included style preset tokens for 'glow'" not in result.stdout:
+            raise AssertionError("style selection was not reported")
+
+        catalog = json.loads((ROOT / "catalog.json").read_text(encoding="utf-8"))["components"]
+        all_destination = Path(temp) / "all-components"
+        with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
+            for slug in catalog:
+                installer.install_component(catalog={"components": catalog}, slug=slug, dest_dir=all_destination, include_previews=True)
+
+        sentinel = Path(temp) / "sentinel.txt"
+        sentinel.write_text("keep", encoding="utf-8")
+        linked = destination / "components/motion/metric-card.tsx"
+        linked.parent.mkdir(parents=True, exist_ok=True)
+        os.symlink(sentinel, linked)
+        catalog = {
+            "unsafe": {
+                "name": "Unsafe",
+                "component_files": ["components/motion/metric-card.tsx"],
+                "util_files": [],
+                "preview_files": [],
+                "doc_path": "references/motion/metric-card.md",
+                "dependencies": [],
+            },
+            "traversal": {
+                "name": "Traversal",
+                "component_files": ["../outside.tsx"],
+                "util_files": [],
+                "preview_files": [],
+                "doc_path": "references/motion/metric-card.md",
+                "dependencies": [],
+            },
+        }
+        expect_exit_one(installer, {"components": catalog}, "unsafe", destination)
+        expect_exit_one(installer, {"components": catalog}, "traversal", Path(temp) / "other")
+        if sentinel.read_text(encoding="utf-8") != "keep":
+            raise AssertionError("installer followed a destination symlink")
+
+    for args in ([str(VERIFY)], ["-O", str(VERIFY)]):
+        result = subprocess.run([sys.executable, *args], cwd=ROOT, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise AssertionError(result.stderr)
+
+    generated = [ROOT / "README.md", ROOT / "SKILL.md"]
+    before = {path: path.read_bytes() for path in generated}
+    result = subprocess.run(
+        [sys.executable, "-B", str(BUILD_DOCS)], cwd=ROOT, capture_output=True, text=True
+    )
+    if result.returncode != 0:
+        raise AssertionError(result.stderr)
+    changed = [path.name for path in generated if path.read_bytes() != before[path]]
+    if changed:
+        raise AssertionError(f"generated docs are stale: {', '.join(changed)}")
+
+    if b"\r" in (ROOT / "SKILL.md").read_bytes():
+        raise AssertionError("SKILL.md contains carriage returns")
+    print("Release checks: PASS")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/updater.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export * from "../bin/updater.mjs";
+import { checkAndAutoUpdate } from "../bin/updater.mjs";
+
+const force = process.argv.includes("--force") || process.argv.includes("-f");
+const silent = process.argv.includes("--silent") || process.argv.includes("-s");
+checkAndAutoUpdate({ force, silent })
+  .then(() => process.exit(0))
+  .catch(() => process.exit(0));

package/scripts/verify_skill.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Fast, dependency-free integrity gate for the Motion UI skill package."""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+FORBIDDEN = ("b" + "eui", "starc" + "007/ui-components")
+
+
+def require(condition, detail):
+    if not condition:
+        raise RuntimeError(f"Integrity check failed: {detail}")
+
+
+def main() -> int:
+    catalog = json.loads((ROOT / "catalog.json").read_text(encoding="utf-8"))
+    components = catalog.get("components", {})
+    expected_categories = {"motion": 80, "agents": 17, "blocks": 33, "craft": 209}
+    actual_categories = {
+        category: sum(item.get("category") == category for item in components.values())
+        for category in expected_categories
+    }
+    require(len(components) == 339, len(components))
+    require(actual_categories == expected_categories, actual_categories)
+    require((ROOT / "SKILL.md").is_file(), "SKILL.md")
+    require((ROOT / "lib/styles.ts").is_file(), "lib/styles.ts")
+    require((ROOT / "references/guides/style-presets.md").is_file(), "style guide")
+    require(not list((ROOT / "skills").rglob("SKILL.md")), "nested skill entrypoint")
+    require(not list((ROOT / ".agents").rglob("SKILL.md")), "nested skill entrypoint")
+
+    listed = []
+    for slug, item in components.items():
+        listed.append(slug)
+        for field in ("component_files", "util_files", "preview_files"):
+            for relative in item.get(field, []):
+                path = Path(relative)
+                require(not path.is_absolute() and ".." not in path.parts, relative)
+                require((ROOT / path).is_file(), relative)
+        doc_path = Path(item["doc_path"])
+        require(not doc_path.is_absolute() and ".." not in doc_path.parts, item["doc_path"])
+        require((ROOT / doc_path).is_file(), item["doc_path"])
+
+    text = "\n".join(
+        path.read_text(encoding="utf-8", errors="ignore")
+        for path in ROOT.rglob("*")
+        if path.is_file()
+        and not {".git", "node_modules", "__pycache__", "promo"}.intersection(path.parts)
+        and path.suffix.lower() in {".md", ".json", ".ts", ".tsx", ".py", ".yaml", ".yml", ".html", ".js", ".css", ".txt"}
+    ).lower()
+    for name in ("README.md", "SKILL.md"):
+        require(b"\r" not in (ROOT / name).read_bytes(), f"carriage return in {name}")
+    for forbidden in FORBIDDEN:
+        require(forbidden not in text, forbidden)
+
+    row_sets = []
+    for name in ("README.md", "SKILL.md"):
+        content = (ROOT / name).read_text(encoding="utf-8")
+        rows = re.findall(
+            r"^\| \*\*(.+?)\*\* \| `([^`]+)` \| .*? \| \[`[^`]+`\]\(([^)]+)\) \| \[Guide\]\(([^)]+)\) \|",
+            content,
+            re.M,
+        )
+        require(len(rows) == 339, (name, len(rows)))
+        require({slug for _, slug, _, _ in rows} == set(listed), name)
+        for _, _, primary, doc in rows:
+            require((ROOT / primary).is_file(), primary)
+            require((ROOT / doc).is_file(), doc)
+        row_sets.append(rows)
+    require(row_sets[0] == row_sets[1], "README and SKILL tables differ")
+    require((ROOT / "agents/openai.yaml").is_file(), "agents/openai.yaml")
+    require((ROOT / "references/codex-install.md").is_file(), "references/codex-install.md")
+    require((ROOT / "prompts/install-motion-ui.md").is_file(), "prompts/install-motion-ui.md")
+    require((ROOT / "scripts/test_release.py").is_file(), "scripts/test_release.py")
+    require((ROOT / "evals/catalog_eval.py").is_file(), "evals/catalog_eval.py")
+    print("Motion UI skill integrity: PASS (339 components, 80/17/33/209 categories)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())