@xaviele/ag-kit 1.0.0

package/template/.agent/skills/webapp-testing/scripts/playwright_runner.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Skill: webapp-testing
+Script: playwright_runner.py
+Purpose: Run basic Playwright browser tests
+Usage: python playwright_runner.py <url> [--screenshot]
+Output: JSON with page info, health status, and optional screenshot path
+Note: Requires playwright (pip install playwright && playwright install chromium)
+Screenshots: Saved to system temp directory (auto-cleaned by OS)
+"""
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime
+
+# Fix Windows console encoding for Unicode output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass  # Python < 3.7
+
+try:
+    from playwright.sync_api import sync_playwright
+    PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    PLAYWRIGHT_AVAILABLE = False
+
+
+def run_basic_test(url: str, take_screenshot: bool = False) -> dict:
+    """Run basic browser test on URL."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {
+            "error": "Playwright not installed",
+            "fix": "pip install playwright && playwright install chromium"
+        }
+    
+    result = {
+        "url": url,
+        "timestamp": datetime.now().isoformat(),
+        "status": "pending"
+    }
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                viewport={"width": 1280, "height": 720},
+                user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            )
+            page = context.new_page()
+            
+            # Navigate
+            response = page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic info
+            result["page"] = {
+                "title": page.title(),
+                "url": page.url,
+                "status_code": response.status if response else None
+            }
+            
+            # Health checks
+            result["health"] = {
+                "loaded": response.ok if response else False,
+                "has_title": bool(page.title()),
+                "has_h1": page.locator("h1").count() > 0,
+                "has_links": page.locator("a").count() > 0,
+                "has_images": page.locator("img").count() > 0
+            }
+            
+            # Console errors
+            console_errors = []
+            page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+            
+            # Performance metrics
+            result["performance"] = {
+                "dom_content_loaded": page.evaluate("window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart"),
+                "load_complete": page.evaluate("window.performance.timing.loadEventEnd - window.performance.timing.navigationStart")
+            }
+            
+            # Screenshot - uses system temp directory (cross-platform, auto-cleaned)
+            if take_screenshot:
+                # Cross-platform: Windows=%TEMP%, Linux/macOS=/tmp
+                screenshot_dir = os.path.join(tempfile.gettempdir(), "maestro_screenshots")
+                os.makedirs(screenshot_dir, exist_ok=True)
+                screenshot_path = os.path.join(screenshot_dir, f"screenshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+                page.screenshot(path=screenshot_path, full_page=True)
+                result["screenshot"] = screenshot_path
+                result["screenshot_note"] = "Saved to temp directory (auto-cleaned by OS)"
+            
+            # Element counts
+            result["elements"] = {
+                "links": page.locator("a").count(),
+                "buttons": page.locator("button").count(),
+                "inputs": page.locator("input").count(),
+                "images": page.locator("img").count(),
+                "forms": page.locator("form").count()
+            }
+            
+            browser.close()
+            
+            result["status"] = "success" if result["health"]["loaded"] else "failed"
+            result["summary"] = "[OK] Page loaded successfully" if result["status"] == "success" else "[X] Page failed to load"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+        result["summary"] = f"[X] Error: {str(e)[:100]}"
+    
+    return result
+
+
+def run_accessibility_check(url: str) -> dict:
+    """Run basic accessibility check."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {"error": "Playwright not installed"}
+    
+    result = {"url": url, "accessibility": {}}
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic a11y checks
+            result["accessibility"] = {
+                "images_with_alt": page.locator("img[alt]").count(),
+                "images_without_alt": page.locator("img:not([alt])").count(),
+                "buttons_with_label": page.locator("button[aria-label], button:has-text('')").count(),
+                "links_with_text": page.locator("a:has-text('')").count(),
+                "form_labels": page.locator("label").count(),
+                "headings": {
+                    "h1": page.locator("h1").count(),
+                    "h2": page.locator("h2").count(),
+                    "h3": page.locator("h3").count()
+                }
+            }
+            
+            browser.close()
+            result["status"] = "success"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+    
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({
+            "error": "Usage: python playwright_runner.py <url> [--screenshot] [--a11y]",
+            "examples": [
+                "python playwright_runner.py https://example.com",
+                "python playwright_runner.py https://example.com --screenshot",
+                "python playwright_runner.py https://example.com --a11y"
+            ]
+        }, indent=2))
+        sys.exit(1)
+    
+    url = sys.argv[1]
+    take_screenshot = "--screenshot" in sys.argv
+    check_a11y = "--a11y" in sys.argv
+    
+    if check_a11y:
+        result = run_accessibility_check(url)
+    else:
+        result = run_basic_test(url, take_screenshot)
+    
+    print(json.dumps(result, indent=2))

package/template/.agent/skills/zalo-mini-app/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: zalo-mini-app
+description: Build Zalo Mini Apps - lightweight web apps running inside Zalo super-app. This skill provides ZaUI components (Button, Input, Modal, Tabs, Avatar, etc.), JavaScript APIs (authorize, getUserInfo, getPhoneNumber, getLocation, Storage, Camera), Checkout SDK for payments, design guidelines, and development tools. Use when building Mini Apps, using ZaUI components, calling Zalo APIs, integrating payments, converting web apps to Mini Apps, or following Zalo design standards.
+---
+
+# Zalo Mini App Development
+
+Build Mini Apps for the Zalo platform using React, ZaUI components, and Zalo SDK APIs.
+
+## Quick Start
+```bash
+npm install -g zmp-cli
+zmp create my-app && cd my-app && zmp start
+```
+
+See [getting-started.md](./references/getting-started.md) for full setup, deployment, and app-config.json.
+
+## Core Packages
+```bash
+npm install zmp-ui zmp-sdk
+```
+
+```js
+import { Button, Input, Modal } from "zmp-ui";
+import "zmp-ui/zaui.css";
+import { getUserInfo, authorize } from "zmp-sdk/apis";
+```
+
+## References
+
+### APIs
+- [api-overview.md](./references/api-overview.md) - API categories & patterns
+- [api-user.md](./references/api-user.md) - authorize, getUserInfo, getPhoneNumber
+- [api-storage.md](./references/api-storage.md) - setItem, getItem, storage APIs
+- [api-ui.md](./references/api-ui.md) - showToast, navigation, routing
+- [api-device.md](./references/api-device.md) - location, camera, QR, NFC
+- [api-zalo.md](./references/api-zalo.md) - followOA, openChat, share
+
+### ZaUI Components
+- [zaui-overview.md](./references/zaui-overview.md) - Component list & design tokens
+- [zaui-layout.md](./references/zaui-layout.md) - App, Page, Header, Tabs, Router
+- [zaui-display.md](./references/zaui-display.md) - Avatar, Icon, List, Swiper
+- [zaui-form.md](./references/zaui-form.md) - Button, Input, Select, DatePicker
+- [zaui-overlay.md](./references/zaui-overlay.md) - Modal, Sheet, ActionSheet
+
+### Design & Setup
+- [design-guidelines.md](./references/design-guidelines.md) - Colors, typography, UX
+- [getting-started.md](./references/getting-started.md) - Setup, deploy, publish
+- [web-design-guidelines.md](./references/web-design-guidelines.md) - Accessibility, forms, animations, touch, i18n
+
+### Performance & React
+- [react-best-practices.md](./references/react-best-practices.md) - Waterfalls, bundle size, re-renders, JS performance
+
+## Common Patterns
+
+### Get User Info
+```js
+const { userInfo } = await getUserInfo({ autoRequestPermission: true });
+// { id, name, avatar, followedOA }
+```
+
+### Basic Page Layout
+```jsx
+<App>
+  <Page>
+    <Header title="Home" />
+    <List>
+      <List.Item title="Item" suffix={<Icon icon="zi-chevron-right" />} />
+    </List>
+  </Page>
+  <BottomNavigation fixed>
+    <BottomNavigation.Item key="home" label="Home" icon={<Icon icon="zi-home" />} />
+  </BottomNavigation>
+</App>
+```
+
+## Resources
+- Docs: https://miniapp.zaloplatforms.com/documents/
+- Mini App Center: https://miniapp.zaloplatforms.com/
+- React Best Practices: https://react.dev
+- SWR: https://swr.vercel.app

package/template/.agent/skills/zalo-mini-app/references/api-device.md

@@ -0,0 +1,121 @@
+# Device & Media APIs
+
+## Location
+
+### getLocation
+Get GPS coordinates (requires permission).
+```js
+import { getLocation } from "zmp-sdk/apis";
+
+const { latitude, longitude, accuracy } = await getLocation({});
+```
+
+## Camera
+
+### createCameraContext
+Create camera controller for streaming.
+```js
+import { createCameraContext } from "zmp-sdk/apis";
+
+const camera = createCameraContext();
+
+await camera.start({
+  targetElement: document.getElementById("camera-view"),
+  facing: "back"  // "front" | "back"
+});
+
+const photo = await camera.takePhoto({});
+await camera.stop();
+```
+
+Camera methods:
+- `start()` - Start streaming
+- `stop()` - Stop streaming
+- `pause()` / `resume()`
+- `takePhoto()` - Capture image
+- `flip()` - Switch front/back
+- `setMirror(true)` - Mirror mode
+
+### requestCameraPermission
+Request camera access.
+```js
+import { requestCameraPermission } from "zmp-sdk/apis";
+
+await requestCameraPermission({});
+```
+
+## File & Media
+
+### chooseImage
+Select images from gallery.
+```js
+import { chooseImage } from "zmp-sdk/apis";
+
+const { tempFilePaths } = await chooseImage({
+  count: 9,
+  sourceType: ["album", "camera"]
+});
+```
+
+### openMediaPicker
+Open media picker.
+```js
+import { openMediaPicker } from "zmp-sdk/apis";
+
+const { files } = await openMediaPicker({
+  type: "image",  // "image" | "video" | "file"
+  maxSelection: 5
+});
+```
+
+### saveImageToGallery / saveVideoToGallery
+Save media to device gallery.
+```js
+import { saveImageToGallery } from "zmp-sdk/apis";
+
+await saveImageToGallery({
+  imageUrl: "https://example.com/image.jpg"
+});
+```
+
+## Scanning
+
+### scanQRCode
+Scan QR/barcode.
+```js
+import { scanQRCode } from "zmp-sdk/apis";
+
+const { content } = await scanQRCode({});
+```
+
+### scanNFC
+Read NFC tag.
+```js
+import { checkNFC, scanNFC } from "zmp-sdk/apis";
+
+const { available } = await checkNFC({});
+if (available) {
+  const { data } = await scanNFC({});
+}
+```
+
+## Network
+
+### getNetworkType
+Check connection type.
+```js
+import { getNetworkType } from "zmp-sdk/apis";
+
+const { networkType } = await getNetworkType({});
+// "wifi" | "4g" | "3g" | "2g" | "none"
+```
+
+## Screen
+
+### keepScreen / vibrate
+```js
+import { keepScreen, vibrate } from "zmp-sdk/apis";
+
+keepScreen({ on: true });  // Keep screen awake
+vibrate({});               // Vibrate device
+```

package/template/.agent/skills/zalo-mini-app/references/api-overview.md

@@ -0,0 +1,88 @@
+# Zalo Mini App API Overview
+
+## Installation
+```bash
+npm install zmp-sdk
+```
+
+## Import Pattern
+```js
+import { apiName } from "zmp-sdk/apis";
+```
+
+## API Categories
+
+### User & Authorization
+See [api-user.md](./api-user.md)
+- `authorize` - Request permissions
+- `getUserID` - Get user ID
+- `getUserInfo` - Get user name, avatar
+- `getPhoneNumber` - Get phone number
+- `getAccessToken` - Get auth token
+- `getSetting` - Get user settings
+
+### Storage
+See [api-storage.md](./api-storage.md)
+- `setItem`, `getItem`, `removeItem`, `clear`
+- `getStorageInfo`
+
+### UI & Navigation
+See [api-ui.md](./api-ui.md)
+- `showToast`, `closeLoading`
+- `configAppView`, `setNavigationBarColor/Title/LeftButton`
+- `hideKeyboard`
+
+### Routing
+- `closeApp` - Close mini app
+- `openMiniApp` - Open another mini app
+- `openWebview` - Open external URL
+- `sendDataToPreviousMiniApp` - Send data back
+- `getRouteParams` - Get URL params
+
+### Device & Media
+See [api-device.md](./api-device.md)
+- `getLocation` - GPS location
+- `createCameraContext` - Camera control
+- `chooseImage`, `openMediaPicker`
+- `saveImageToGallery`, `saveVideoToGallery`
+- `scanQRCode`, `scanNFC`
+- `getNetworkType`, `vibrate`, `keepScreen`
+
+### Zalo Features
+See [api-zalo.md](./api-zalo.md)
+- `followOA`, `unfollowOA`, `interactOA`
+- `openChat`, `openProfile`, `openShareSheet`
+- `createShortcut`, `addRating`
+
+## Events
+```js
+import { events, EventName } from "zmp-sdk/apis";
+
+events.on(EventName.NetworkChanged, (data) => {});
+events.on(EventName.AppPaused, () => {});
+events.on(EventName.AppResumed, () => {});
+events.on(EventName.OpenApp, () => {});
+events.on(EventName.OnDataCallback, (data) => {});
+```
+
+## Error Handling
+```js
+import { AppError } from "zmp-sdk";
+
+try {
+  const result = await someApi();
+} catch (error) {
+  if (error instanceof AppError) {
+    console.log(error.code, error.message);
+  }
+}
+```
+
+Common error codes:
+- `-1401`: User denied permission
+- `-1`: Unknown error
+
+## Permission Notes
+- Some APIs require Zalo approval before use
+- Admin accounts can test all APIs without approval
+- User-sensitive APIs (phone, location) need user consent

package/template/.agent/skills/zalo-mini-app/references/api-storage.md

@@ -0,0 +1,74 @@
+# Storage APIs
+
+Local storage on user's device, persists across sessions.
+
+## setItem
+Save data to storage.
+```js
+import { setItem } from "zmp-sdk/apis";
+
+await setItem({
+  data: {
+    key1: "value1",
+    key2: { nested: "object" },
+    key3: [1, 2, 3]
+  }
+});
+```
+
+## getItem
+Retrieve stored data.
+```js
+import { getItem } from "zmp-sdk/apis";
+
+const { key1, key2 } = await getItem({
+  keys: ["key1", "key2"]
+});
+```
+
+## removeItem
+Delete specific keys.
+```js
+import { removeItem } from "zmp-sdk/apis";
+
+await removeItem({
+  keys: ["key1", "key2"]
+});
+```
+
+## clear
+Clear all storage.
+```js
+import { clear } from "zmp-sdk/apis";
+
+await clear({});
+```
+
+## getStorageInfo
+Get storage usage info.
+```js
+import { getStorageInfo } from "zmp-sdk/apis";
+
+const { keys, currentSize, limitSize } = await getStorageInfo({});
+```
+
+## Best Practices
+- Store only essential data
+- Use JSON for complex objects
+- Check storage limits before saving
+- Handle errors for quota exceeded
+
+## Example: Address Book Cache
+```js
+async function getAddresses() {
+  const { addresses } = await getItem({ keys: ["addresses"] });
+  return addresses || [];
+}
+
+async function saveAddress(address) {
+  const addresses = await getAddresses();
+  addresses.push(address);
+  await setItem({ data: { addresses } });
+  return addresses;
+}
+```

package/template/.agent/skills/zalo-mini-app/references/api-ui.md

@@ -0,0 +1,124 @@
+# UI & Navigation APIs
+
+## showToast
+Display a toast message.
+```js
+import { showToast } from "zmp-sdk/apis";
+
+showToast({
+  message: "Operation successful",
+  duration: 2000  // ms
+});
+```
+
+## closeLoading
+Hide splash loading screen.
+```js
+import { closeLoading } from "zmp-sdk/apis";
+
+closeLoading({});
+```
+
+## configAppView
+Configure status bar, action bar, and safe area.
+```js
+import { configAppView } from "zmp-sdk/apis";
+
+configAppView({
+  headerColor: "#1843EF",
+  headerTextColor: "white",
+  statusBarType: "normal",      // "normal" | "transparent"
+  actionBarHidden: false,
+  hideAndroidBottomNavigationBar: true,
+  hideIOSSafeAreaBottom: false
+});
+```
+
+## setNavigationBarColor
+Change navigation bar color.
+```js
+import { setNavigationBarColor } from "zmp-sdk/apis";
+
+setNavigationBarColor({
+  color: "#FF5722"
+});
+```
+
+## setNavigationBarTitle
+Change navigation bar title.
+```js
+import { setNavigationBarTitle } from "zmp-sdk/apis";
+
+setNavigationBarTitle({
+  title: "New Title"
+});
+```
+
+## setNavigationBarLeftButton
+Set left button type.
+```js
+import { setNavigationBarLeftButton } from "zmp-sdk/apis";
+
+setNavigationBarLeftButton({
+  type: "back"  // "back" | "home"
+});
+```
+
+## hideKeyboard
+Dismiss the keyboard.
+```js
+import { hideKeyboard } from "zmp-sdk/apis";
+
+hideKeyboard({});
+```
+
+## Routing APIs
+
+### closeApp
+Close mini app.
+```js
+import { closeApp } from "zmp-sdk/apis";
+
+closeApp({});
+```
+
+### openMiniApp
+Open another mini app.
+```js
+import { openMiniApp } from "zmp-sdk/apis";
+
+openMiniApp({
+  appId: "other-mini-app-id",
+  path: "/page?param=value"
+});
+```
+
+### openWebview
+Open URL in webview.
+```js
+import { openWebview } from "zmp-sdk/apis";
+
+openWebview({
+  url: "https://example.com"
+});
+```
+
+### sendDataToPreviousMiniApp
+Send data back to calling mini app.
+```js
+import { sendDataToPreviousMiniApp } from "zmp-sdk/apis";
+
+sendDataToPreviousMiniApp({
+  data: { result: "success" }
+});
+```
+
+### getRouteParams
+Get URL parameters.
+```js
+import { getRouteParams } from "zmp-sdk/apis";
+
+const params = getRouteParams();
+// For URL: /page?id=123&type=product
+// Returns: { id: "123", type: "product" }
+```