heraspec 0.1.13 → 0.1.15

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)