heraspec 0.1.12 → 0.1.14

package/dist/core/templates/skills/deploy-documentation-skill.md

@@ -0,0 +1,408 @@
+---
+name: deploy-documentation
+description: Tự động hoá quy trình chụp screenshot và cập nhật documentation sau mỗi lần build & deploy — discover routes, generate manifest, capture screenshots, update HTML. Hoạt động với mọi loại web application.
+projectType: all
+---
+
+# Deploy Documentation — Auto Screenshot & Docs Generator
+
+## Purpose
+
+Skill này tự động hoá quy trình chụp ảnh màn hình và cập nhật documentation sau mỗi lần build & deploy sản phẩm. Thay vì developer phải truy cập thủ công từng trang, chụp ảnh, rồi cập nhật landing page — skill này thực hiện toàn bộ quy trình một cách tự động và nhất quán.
+
+**Vấn đề giải quyết:**
+- Sau khi build xong plugin/module/software, developer phải truy cập từng trang tính năng trên site
+- Chụp ảnh thủ công, dễ sai sót (quên cập nhật mô tả)
+- Tốn thời gian khi có nhiều route, lặp lại mỗi version
+
+## When to Use
+
+- Sau mỗi lần release / deploy phiên bản mới
+- Khi cần sync documentation screenshots với UI thực tế
+- Khi thêm tính năng mới chưa có trong manifest
+- Khi cần chụp ảnh từ nhiều site khác nhau (local, demo, client)
+
+---
+
+## Architecture: 2 Phases
+
+```
+Phase 1: DISCOVER — Quét codebase → Suggest manifest entries
+Phase 2: CAPTURE  — Đọc manifest → Login → Navigate → Screenshot → Update HTML
+```
+
+---
+
+## Phase 1: Route Discovery & Manifest Generation
+
+### Mục đích
+Tự động quét codebase để phát hiện routes/pages, sau đó suggest thêm entries vào `deploy_manifest.json`.
+
+### Cách hoạt động
+
+**1. Quét routes — tìm tất cả route definitions trong codebase:**
+
+| Project Type | Source files |
+|---|---|
+| Perfex CRM Module | `config/my_routes.php` + controller method names |
+| Laravel App | `routes/web.php`, `routes/api.php` |
+| WordPress Plugin | `add_menu_page()`, `add_submenu_page()` hooks |
+| Next.js / Vite SPA | `pages/` directory, router config files |
+| Electron App | Window/view registrations |
+| Generic | Navigation config files, sitemap |
+
+**2. Quét menu registrations — tìm sidebar/nav menu items:**
+- Perfex CRM: `$this->app_menu->add_sidebar_menu_item()` calls
+- WordPress: `add_menu_page()`, `add_submenu_page()`
+- Generic: tìm navigation config files
+
+**3. Quét migration changelog:**
+- Parse `logChanged()` hoặc `CHANGELOG.md` để detect features mới chưa có trong manifest
+
+**4. Cross-reference với manifest:**
+- So sánh routes discovered vs entries đã khai báo → suggest entries còn thiếu
+
+### Discovery Scan Targets (Perfex CRM modules — example)
+
+```
+modules/{module}/config/my_routes.php       → Route definitions
+modules/{module}/data_builder.php           → Menu items (add_sidebar_menu_item)
+modules/{module}/controllers/*.php          → Controller methods = pages
+modules/{module}/views/admin/**/*.php       → View templates
+modules/{module}/migrations/*_version_*.php → Changelog (logChanged)
+```
+
+### Output Format — Suggested Entry
+
+```json
+{
+  "id": "auto-discovered-{route}",
+  "filename": "{Feature-Name}-{Product}.png",
+  "title": "{Feature Name}",
+  "route": "/admin/{module}/{controller}/{method}",
+  "wait_for": "#app, .panel, .table-responsive",
+  "section": "core-features",
+  "actions_before": [
+    { "action": "wait", "ms": 2000 }
+  ],
+  "_discovered_from": "controller: Builder.php → method: index()",
+  "_status": "suggested"
+}
+```
+
+> **IMPORTANT**: Entries có `_status: "suggested"` cần user review và confirm trước khi chạy Phase 2. Agent MUST NOT auto-proceed.
+
+### Site Suggestion Logic (khi discover)
+
+| Loại page | Site đề xuất | Lý do |
+|---|---|---|
+| Admin management pages | `local` | Không cần real data |
+| Charts, runtime reports | `demo` | Cần data đẹp, trực quan |
+| Public embed / iframe | `demo` | Cần public view đã setup |
+| Client-specific feature | `client_x` | Cần data thực tế của client |
+
+---
+
+## Phase 2: Screenshot Capture & Documentation Update
+
+### Prerequisites
+- File `deploy_manifest.json` đã được review và xác nhận
+- Site đang chạy và accessible tại `base_url`
+- Credentials hợp lệ
+
+### Step 1: Build Site Groups
+
+```
+1. Đọc manifest.sites{} và manifest.default_site
+2. Với mỗi entry trong screenshots[]:
+   - Nếu entry có "site" key → site = sites[entry.site]
+   - Nếu không → site = sites[default_site]
+3. Group entries by site key → { local: [...], demo: [...], client_x: [...] }
+```
+
+### Step 2: Login (một lần mỗi site)
+
+```
+Foreach unique_site in groups:
+  site_config = sites[unique_site]
+  1. Mở browser tab mới tại: {site_config.base_url}{site_config.login_url}
+  2. Điền credentials:
+       - email_selector ← site_config.login_form.email_selector
+       - password_selector ← site_config.login_form.password_selector
+  3. Click submit: site_config.login_form.submit_selector
+  4. Chờ redirect hoặc dashboard element xuất hiện
+  5. Lưu session/cookies cho site này
+  Log: ✅ Logged in to {site_config.base_url} / ❌ Login failed
+```
+
+**login_form supports:**
+- Perfex CRM: `input[name='email']` + `input[name='password']`
+- WordPress: `input#user_login` + `input#user_pass`
+- Laravel / generic: any valid CSS selector
+
+### Step 3: Screenshot Loop
+
+```
+Foreach entry in manifest.screenshots[]:
+  site_config = sites[entry.site || default_site]
+  base_url    = site_config.base_url
+
+  1. Navigate tới {base_url}{entry.route}
+     Resolve dynamic tokens nếu có:
+       {first_view_id}      → Scrape view list page → first row ID
+       {first_view_route}   → Scrape view list page → first row route slug
+       {first_public_route} → Scrape views → first with public_access indicator
+       {latest_record_id}   → Scrape or sort by date → most recent ID
+
+  2. Set viewport: entry.viewport || manifest.defaults.viewport
+
+  3. Execute actions_before[] theo thứ tự:
+       wait                → sleep(ms)
+       click               → click(selector)
+       click_first_visible → find first visible element → click
+       scroll_down         → window.scrollBy(0, px)
+       scroll_to           → element.scrollIntoView()
+       type                → type text into selector (for search/filter inputs)
+
+  4. Wait for: entry.wait_for selector to appear in DOM
+
+  5. Capture screenshot:
+       format = entry.format || manifest.defaults.format
+       Save → {output.images_dir}/{entry.filename}
+
+  Log: ✅ {entry.id} → {entry.filename} / ❌ reason
+```
+
+### Step 4: HTML Update (Optional)
+
+```
+1. Đọc index.html
+2. Cập nhật version number từ source code
+3. Cập nhật date (Updated: {current month year})
+4. Parse changelog từ migration file → inject vào #changelog-content
+5. Verify tất cả <img src="images/..."> đều có file tương ứng
+6. Save index.html
+```
+
+---
+
+## Manifest Format Reference
+
+Tạo file `deploy_manifest.json` **cùng folder với `AGENTS.heraspec.md` và thư mục `heraspec/`** của project/module đó — không nhất thiết là root của toàn bộ monorepo:
+
+```json
+{
+  "product": {
+    "name": "Product Name",
+    "tagline": "Short description",
+    "version_source": "path/to/version_file",
+    "changelog_source": "path/to/migration_or_changelog"
+  },
+
+  "sites": {
+    "local": {
+      "base_url": "https://localhost:PORT",
+      "login_url": "/admin/authentication",
+      "login_form": {
+        "email_selector": "input[name='email']",
+        "password_selector": "input[name='password']",
+        "submit_selector": "button[type='submit']"
+      },
+      "credentials": {
+        "email": "admin@admin.com",
+        "password": "password"
+      },
+      "description": "Local dev"
+    },
+    "demo": {
+      "base_url": "https://demo.example.com",
+      "login_url": "/admin/authentication",
+      "login_form": {
+        "email_selector": "input[name='email']",
+        "password_selector": "input[name='password']",
+        "submit_selector": "button[type='submit']"
+      },
+      "credentials": {
+        "email": "admin@demo.com",
+        "password": "password"
+      },
+      "description": "Live demo site for marketing screenshots"
+    }
+  },
+
+  "default_site": "local",
+
+  "output": {
+    "images_dir": "path/to/documentation/images",
+    "html_file": "path/to/documentation/index.html"
+  },
+
+  "defaults": {
+    "viewport": { "width": 1440, "height": 900 },
+    "format": "png",
+    "wait_ms": 2000
+  },
+
+  "screenshots": [
+    {
+      "id": "feature-overview",
+      "filename": "Feature-Overview-ProductName.png",
+      "title": "Feature Overview",
+      "route": "/admin/module/page",
+      "wait_for": "#app, .panel, .table-responsive",
+      "section": "core-features",
+      "actions_before": [
+        { "action": "wait", "ms": 2000 }
+      ]
+    },
+    {
+      "id": "feature-on-demo",
+      "site": "demo",
+      "filename": "Feature-Demo-ProductName.png",
+      "title": "Feature (Demo Data)",
+      "route": "/admin/module/page",
+      "wait_for": ".chart-container",
+      "section": "core-features",
+      "actions_before": [
+        { "action": "wait", "ms": 3000 }
+      ]
+    }
+  ]
+}
+```
+
+### Dynamic Route Tokens
+
+| Token | Resolution |
+|-------|-----------|
+| `{first_view_id}` | ID của record đầu tiên trong view list |
+| `{first_view_route}` | Route slug của view đầu tiên |
+| `{first_public_route}` | Route của view public đầu tiên |
+| `{latest_record_id}` | ID của record mới nhất |
+
+Agent resolves các token này bằng cách scrape trang list hoặc query database.
+
+---
+
+## Prompt Templates
+
+### Full workflow (Discover + Capture):
+
+```
+Sử dụng skill deploy-documentation.
+Project: {module_path}
+Manifest: {manifest_path}
+
+1. Phase 1: Quét codebase tại {module_path}, phát hiện routes/features chưa có trong manifest, suggest entries mới (đề xuất site phù hợp cho từng entry)
+2. Tôi sẽ review và confirm manifest
+3. Phase 2: Login vào từng site trong manifest, chụp tất cả screenshots, lưu vào images_dir
+4. Cập nhật index.html với ảnh mới và changelog
+```
+
+### Chỉ chụp ảnh — tất cả sites (manifest đã sẵn):
+
+```
+Sử dụng skill deploy-documentation.
+Đọc manifest tại {manifest_path}.
+Login vào từng site được khai báo, chụp tất cả screenshots theo manifest, lưu vào output.images_dir.
+```
+
+### Chỉ chụp ảnh — 1 site cụ thể:
+
+```
+Sử dụng skill deploy-documentation.
+Đọc manifest tại {manifest_path}.
+Chỉ chụp các screenshots thuộc site "demo".
+Login vào demo site, navigate và capture, lưu vào images_dir.
+```
+
+### Chỉ chụp lại 1 số ảnh cụ thể:
+
+```
+Sử dụng skill deploy-documentation.
+Đọc manifest tại {manifest_path}.
+Chỉ chụp lại các entries: {id1}, {id2}, {id3}.
+Sử dụng site mặc định (default_site) trừ khi entry có khai báo site riêng.
+```
+
+### Chỉ discover — suggest entries mới:
+
+```
+Sử dụng skill deploy-documentation.
+Quét codebase tại {module_path}, so sánh với manifest tại {manifest_path}.
+Suggest entries mới cho features/routes chưa được khai báo.
+Với mỗi entry mới: đề xuất site phù hợp (local nếu là admin page, demo nếu cần real-data screenshot).
+Không tự thêm vào manifest — liệt kê để tôi review trước.
+```
+
+---
+
+## Compatibility — Supported Project Types
+
+| Project Type | Route Discovery Source |
+|---|---|
+| Perfex CRM Module | `my_routes.php` + controller methods |
+| Laravel App | `routes/web.php` + `routes/api.php` |
+| WordPress Plugin | `add_menu_page()` + `add_submenu_page()` |
+| Next.js / Vite SPA | `pages/` directory + router config |
+| Electron App | Window/view registrations |
+| Generic Web App | Navigation config files, sitemap |
+
+Mỗi project chỉ cần 1 file `deploy_manifest.json` riêng. Cùng skill, cùng workflow.
+
+---
+
+## File Structure (per project/module)
+
+`deploy_manifest.json` nằm **cùng folder với `AGENTS.heraspec.md` và `heraspec/`** của module/project đó:
+
+```
+{heraspec_workspace_dir}/        ← Thư mục chứa AGENTS.heraspec.md
+├── AGENTS.heraspec.md
+├── heraspec/
+├── deploy_manifest.json         ← Đặt tại đây
+└── documentation/
+    ├── index.html
+    └── images/
+```
+
+**Ví dụ với Perfex CRM** (mỗi module là một workspace HeraSpec riêng):
+
+```
+perfex_crm/
+└── modules/
+    ├── data_builder/
+    │   ├── AGENTS.heraspec.md
+    │   ├── heraspec/
+    │   ├── deploy_manifest.json    ← manifest của data_builder
+    │   └── documentation/
+    └── another_module/
+        ├── AGENTS.heraspec.md
+        ├── heraspec/
+        ├── deploy_manifest.json    ← manifest riêng của another_module
+        └── documentation/
+```
+
+> **Rule**: `deploy_manifest.json` luôn nằm cùng cấp với `AGENTS.heraspec.md` và `heraspec/` — dù workspace đó là module con hay project độc lập.
+
+
+---
+
+## Inputs
+
+- `deploy_manifest.json` — manifest file của project (xem templates/deploy_manifest.template.json)
+- Codebase path — để Phase 1 discover routes
+- Running site — để Phase 2 capture screenshots
+
+## Outputs
+
+- Screenshot PNG/WebP files tại `output.images_dir`
+- Updated `index.html` tại `output.html_file`
+- Suggested entries (Phase 1 only) — danh sách để user review
+
+## Limitations
+
+- Yêu cầu browser agent có khả năng điều khiển browser (navigate, click, screenshot)
+- Login session không persistent giữa các lần chạy — phải login lại mỗi session
+- Dynamic tokens (`{first_view_id}`, v.v.) cần site đang có dữ liệu thực
+- HTML auto-update chỉ hoạt động nếu `index.html` có structure đúng format (có `#changelog-content`, `<img>` tags với đúng src pattern)

package/dist/core/templates/skills/design-system-skill.md

@@ -0,0 +1,176 @@
+# Skill: Design System Reference (Cross-Cutting)
+
+## Purpose
+
+This skill provides access to **54 real-world design systems** extracted from production websites (Stripe, Vercel, Linear, Supabase, Apple, etc.) in the Google Stitch DESIGN.md format. Each design system contains detailed color palettes, typography rules, component stylings, shadow systems, and agent-ready prompts.
+
+Use this skill to create UIs that match the look and feel of specific well-known brands, or to find design inspiration from real-world references.
+
+## When to Use
+
+- When user requests UI "like Stripe" / "inspired by Vercel" / "Linear-style"
+- When building a product in a specific industry (fintech, devtools, AI) and need proven design patterns
+- When you need precise color values, font weights, shadow values from real design systems
+- When creating a DESIGN.md for a new project
+- When comparing design approaches (e.g., Stripe vs Vercel shadow philosophies)
+
+## Prerequisites
+
+None — this skill uses the same search engine as UI/UX skill.
+
+## Step-by-Step Process
+
+### Step 1: Identify the Design Reference
+
+Determine which design system(s) are relevant:
+
+**By brand name:**
+```bash
+python3 scripts/search.py "stripe" --domain design-system
+python3 scripts/search.py "linear dark mode" --domain design-system  
+python3 scripts/search.py "vercel minimal" --domain design-system
+```
+
+**By style/industry:**
+```bash
+python3 scripts/search.py "fintech premium dark" --domain design-system
+python3 scripts/search.py "developer tools dark emerald" --domain design-system
+python3 scripts/search.py "ai platform warm editorial" --domain design-system
+python3 scripts/search.py "enterprise blue structured" --domain design-system
+```
+
+**By visual technique:**
+```bash
+python3 scripts/search.py "shadow-as-border" --domain design-system
+python3 scripts/search.py "neon glow dark" --domain design-system
+python3 scripts/search.py "blue-tinted shadows" --domain design-system
+python3 scripts/search.py "luminance stacking" --domain design-system
+```
+
+### Step 2: Read the Full DESIGN.md
+
+After finding a matching brand, read the complete DESIGN.md from knowledge base:
+
+```
+knowledge/design-systems/<folder>/DESIGN.md
+```
+
+The `Folder` field in search results tells you the directory name. For example:
+- Stripe → `knowledge/design-systems/stripe/DESIGN.md`
+- Linear → `knowledge/design-systems/linear.app/DESIGN.md`
+- Supabase → `knowledge/design-systems/supabase/DESIGN.md`
+
+### Step 3: Apply the Design System
+
+Use the `Agent_Quick_Prompt` from search results as a starting point, then reference the full DESIGN.md for details:
+
+1. **Colors**: Apply exact hex values from Color Palette section
+2. **Typography**: Use specified fonts, weights, and letter-spacing
+3. **Components**: Follow button, card, input, navigation specifications
+4. **Shadows**: Use exact shadow values (this is often what makes a design "feel" right)
+5. **Spacing**: Follow the spacing scale and border-radius values
+6. **Do's/Don'ts**: Respect the design system's guardrails
+
+### Step 4: Combine with UI/UX Skill
+
+For maximum quality, combine design-system references with other UI/UX skill searches:
+
+```bash
+# 1. Get the design system reference
+python3 scripts/search.py "stripe" --domain design-system
+
+# 2. Get UX guidelines
+python3 scripts/search.py "animation" --domain ux
+python3 scripts/search.py "accessibility" --domain ux
+
+# 3. Get page structure
+python3 scripts/search.py "pricing plans" --domain pages
+
+# 4. Get stack-specific guidelines
+python3 scripts/search.py "responsive layout" --stack html-tailwind
+```
+
+## Available Design Systems
+
+### By Category
+
+| Category | Count | Examples |
+|----------|-------|---------|
+| **AI & ML** | 12 | Claude, Mistral AI, Ollama, Cursor, xAI, ElevenLabs |
+| **Developer Tools** | 14 | Vercel, Linear, Supabase, Raycast, Warp, Sentry |
+| **Infrastructure** | 6 | Stripe, MongoDB, HashiCorp, ClickHouse, Sanity |
+| **Design & Productivity** | 10 | Notion, Figma, Framer, Miro, Airtable, Pinterest |
+| **Fintech & Crypto** | 4 | Coinbase, Revolut, Wise, Kraken |
+| **Enterprise & Consumer** | 8 | Apple, Airbnb, Spotify, BMW, SpaceX, Uber, IBM |
+
+### By Theme
+
+| Theme | Brands |
+|-------|--------|
+| **Dark-mode native** | Linear, Supabase, Cursor, Spotify, SpaceX, Warp, Resend |
+| **Light-first** | Stripe, Vercel, Notion, Apple, Mintlify, Ollama |
+| **Both modes** | IBM, Uber, Framer, Lovable, Cohere, Together AI |
+
+### By Design Philosophy
+
+| Philosophy | Brand | Key Technique |
+|------------|-------|---------------|
+| Weight-as-luxury | Stripe | font-weight: 300 for elegance |
+| Shadow-as-border | Vercel | box-shadow: 0px 0px 0px 1px rgba() |
+| Luminance stacking | Linear | Background opacity stepping for depth |
+| Warm editorial | Claude | Terracotta accent, anti-tech-cold palette |
+| Terminal-native | Resend, Warp | Monospace accents, dark void backgrounds |
+| Full-bleed imagery | SpaceX | Text over cinematic photos |
+
+## Search Reference
+
+```bash
+# Search by brand
+python3 scripts/search.py "<brand-name>" --domain design-system
+
+# Search by keywords
+python3 scripts/search.py "<style-keywords>" --domain design-system
+
+# Search with semantic mode
+python3 scripts/search.py "elegant dark developer tool" --domain design-system --mode hybrid
+
+# Multiple results
+python3 scripts/search.py "fintech" --domain design-system -n 5
+```
+
+## DESIGN.md Format (Google Stitch Standard)
+
+Each DESIGN.md file contains 9 standard sections:
+
+1. **Visual Theme & Atmosphere** — Design philosophy, mood, density
+2. **Color Palette & Roles** — Hex values with semantic roles
+3. **Typography Rules** — Font families, full type scale table
+4. **Component Stylings** — Buttons, cards, inputs with states
+5. **Layout Principles** — Spacing scale, grid, whitespace
+6. **Depth & Elevation** — Shadow system, surface hierarchy
+7. **Do's and Don'ts** — Design guardrails, anti-patterns
+8. **Responsive Behavior** — Breakpoints, touch targets
+9. **Agent Prompt Guide** — Quick reference prompts for AI agents
+
+## Updating Design Systems
+
+Design system files are sourced from [awesome-design-md](https://github.com/VoltAgent/awesome-design-md). To update:
+
+1. Pull latest from `awesome-design-md` repository
+2. Copy updated `DESIGN.md` files to `knowledge/design-systems/<folder>/`
+3. Update `design-systems.csv` in `data/` if new brands are added
+4. Update `index.json` in `knowledge/design-systems/` with new entries
+
+## Tips for Best Results
+
+1. **Be specific** — "dark mode with purple accents" is better than "dark"
+2. **Reference real brands** — "like Stripe" gives much better results than "fintech"
+3. **Read the full DESIGN.md** — The CSV gives a summary, but the DESIGN.md has full specs
+4. **Combine skills** — Design-system + UI/UX + Stack = production-quality output
+5. **Use Agent_Quick_Prompt** — Each entry has a ready-to-use prompt in the CSV
+
+## Links to Other Skills
+
+- **ui-ux**: Use together for comprehensive design system + UX guidelines
+- **documents**: Use to document your project's design system
+- **content-optimization**: Use to optimize CTA placement with brand colors