heraspec 0.1.14 → 0.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +187 -0
- package/README.md +140 -107
- package/bin/heraspec.js +1491 -155
- package/bin/heraspec.js.map +4 -4
- package/dist/cli/index.d.ts +2 -0
- package/dist/commands/audit.d.ts +37 -0
- package/dist/commands/create.d.ts +11 -0
- package/dist/commands/explore.d.ts +17 -0
- package/dist/commands/helper.d.ts +13 -0
- package/dist/commands/hotfix.d.ts +9 -0
- package/dist/commands/make-code.d.ts +14 -0
- package/dist/commands/make-docs.d.ts +36 -0
- package/dist/commands/make-test.d.ts +60 -0
- package/dist/commands/memory.d.ts +101 -0
- package/dist/commands/pack.d.ts +17 -0
- package/dist/commands/show.d.ts +8 -0
- package/dist/commands/skill.d.ts +8 -0
- package/dist/commands/suggest.d.ts +32 -0
- package/dist/commands/validate.d.ts +8 -0
- package/dist/core/archive.d.ts +14 -0
- package/dist/core/config.d.ts +33 -0
- package/dist/core/init.d.ts +97 -0
- package/dist/core/list.d.ts +7 -0
- package/dist/core/memory/config-advisor.d.ts +30 -0
- package/dist/core/memory/context-config.d.ts +14 -0
- package/dist/core/memory/context-generator.d.ts +19 -0
- package/dist/core/memory/index.d.ts +12 -0
- package/dist/core/memory/memory-schema.d.ts +34 -0
- package/dist/core/memory/memory-search.d.ts +45 -0
- package/dist/core/memory/memory-store.d.ts +71 -0
- package/dist/core/memory/memory-types.d.ts +159 -0
- package/dist/core/memory/memory-vector.d.ts +23 -0
- package/dist/core/parsers/code-parser.d.ts +53 -0
- package/dist/core/parsers/markdown-parser.d.ts +18 -0
- package/dist/core/restore.d.ts +9 -0
- package/dist/core/schemas/base.schema.d.ts +55 -0
- package/dist/core/schemas/change.schema.d.ts +35 -0
- package/dist/core/schemas/index.d.ts +7 -0
- package/dist/core/schemas/spec.schema.d.ts +50 -0
- package/dist/core/skills/index.d.ts +6 -0
- package/dist/core/skills/skill-manager.d.ts +28 -0
- package/dist/core/skills/skill-parser.d.ts +24 -0
- package/dist/core/sync.d.ts +6 -0
- package/dist/core/templates/index.d.ts +10 -0
- package/dist/core/templates/skills/README.md +44 -38
- package/dist/core/templates/skills/campaign-plan/skill.md +76 -0
- package/dist/core/templates/skills/campaign-plan/skill.vi.md +76 -0
- package/dist/core/templates/skills/campaign-plan-skill.md +76 -0
- package/dist/core/templates/skills/campaign-plan-skill.vi.md +76 -0
- package/dist/core/templates/skills/code-review/skill.md +70 -0
- package/dist/core/templates/skills/code-review/skill.vi.md +70 -0
- package/dist/core/templates/skills/code-review-skill.md +70 -0
- package/dist/core/templates/skills/code-review-skill.vi.md +70 -0
- package/dist/core/templates/skills/content-creation/skill.md +69 -0
- package/dist/core/templates/skills/content-creation/skill.vi.md +69 -0
- package/dist/core/templates/skills/content-creation-skill.md +69 -0
- package/dist/core/templates/skills/content-creation-skill.vi.md +69 -0
- package/dist/core/templates/skills/content-optimization/skill.md +104 -0
- package/dist/core/templates/skills/debug/skill.md +69 -0
- package/dist/core/templates/skills/debug/skill.vi.md +69 -0
- package/dist/core/templates/skills/debug-skill.md +69 -0
- package/dist/core/templates/skills/debug-skill.vi.md +69 -0
- package/dist/core/templates/skills/deploy-documentation/skill.md +408 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/airbnb/DESIGN.md +246 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/airtable/DESIGN.md +89 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/apple/DESIGN.md +313 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/bmw/DESIGN.md +180 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/cal/DESIGN.md +259 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/claude/DESIGN.md +312 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/clay/DESIGN.md +304 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/clickhouse/DESIGN.md +281 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/cohere/DESIGN.md +266 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/coinbase/DESIGN.md +129 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/composio/DESIGN.md +307 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/cursor/DESIGN.md +309 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/elevenlabs/DESIGN.md +265 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/expo/DESIGN.md +281 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/figma/DESIGN.md +220 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/framer/DESIGN.md +246 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/hashicorp/DESIGN.md +278 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/ibm/DESIGN.md +332 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/index.json +72 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/intercom/DESIGN.md +146 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/kraken/DESIGN.md +125 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/linear.app/DESIGN.md +367 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/lovable/DESIGN.md +298 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/minimax/DESIGN.md +257 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/mintlify/DESIGN.md +326 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/miro/DESIGN.md +108 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/mistral.ai/DESIGN.md +261 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/mongodb/DESIGN.md +266 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/notion/DESIGN.md +309 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/nvidia/DESIGN.md +293 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/ollama/DESIGN.md +267 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/opencode.ai/DESIGN.md +281 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/pinterest/DESIGN.md +230 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/posthog/DESIGN.md +256 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/raycast/DESIGN.md +268 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/replicate/DESIGN.md +261 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/resend/DESIGN.md +303 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/revolut/DESIGN.md +185 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/runwayml/DESIGN.md +244 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/sanity/DESIGN.md +357 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/sentry/DESIGN.md +262 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/spacex/DESIGN.md +194 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/spotify/DESIGN.md +246 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/stripe/DESIGN.md +322 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/supabase/DESIGN.md +255 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/superhuman/DESIGN.md +252 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/together.ai/DESIGN.md +263 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/uber/DESIGN.md +295 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/vercel/DESIGN.md +310 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/voltagent/DESIGN.md +323 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/warp/DESIGN.md +253 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/webflow/DESIGN.md +92 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/wise/DESIGN.md +173 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/x.ai/DESIGN.md +257 -0
- package/dist/core/templates/skills/design-system/knowledge/design-systems/zapier/DESIGN.md +328 -0
- package/dist/core/templates/skills/design-system/skill.md +176 -0
- package/dist/core/templates/skills/documents/skill.md +104 -0
- package/dist/core/templates/skills/e2e-test/skill.md +119 -0
- package/dist/core/templates/skills/email-sequence/skill.md +68 -0
- package/dist/core/templates/skills/email-sequence/skill.vi.md +68 -0
- package/dist/core/templates/skills/email-sequence-skill.md +68 -0
- package/dist/core/templates/skills/email-sequence-skill.vi.md +68 -0
- package/dist/core/templates/skills/git-embed/skill.md +57 -0
- package/dist/core/templates/skills/integration-test/skill.md +118 -0
- package/dist/core/templates/skills/knowledge/README.md +63 -63
- package/dist/core/templates/skills/knowledge/design-systems/index.json +72 -72
- package/dist/core/templates/skills/knowledge/frameworks/php/codeigniter/rise-cms/profile.json +27 -27
- package/dist/core/templates/skills/knowledge/frameworks/php/codeigniter/rise-cms/structure.md +137 -137
- package/dist/core/templates/skills/knowledge/frameworks/php/laravel/botble/profile.json +39 -39
- package/dist/core/templates/skills/knowledge/frameworks/php/laravel/botble/structure.md +207 -207
- package/dist/core/templates/skills/knowledge/frameworks/php/wordpress/core/profile.json +51 -51
- package/dist/core/templates/skills/knowledge/frameworks/php/wordpress/core/structure.md +369 -369
- package/dist/core/templates/skills/knowledge/index.json +65 -65
- package/dist/core/templates/skills/perfex-module/code-quality-guidelines/skill.md +130 -0
- package/dist/core/templates/skills/perfex-module/envato-review-guidelines/skill.md +132 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/scripts/scaffold-module.js +151 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/skill.md +204 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/Test_Module.php +79 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/controller-admin.php +71 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/controller-api.php +58 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/deploy.ps1 +97 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/helper.php +97 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/install.php +30 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/model-main.php +94 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/module-main.php +91 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/package.json +30 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/uninstall.php +11 -0
- package/dist/core/templates/skills/perfex-module/module-codebase/templates/webpack.config.js +163 -0
- package/dist/core/templates/skills/perfex-module/skill.md +50 -0
- package/dist/core/templates/skills/project-memory/skill.md +222 -0
- package/dist/core/templates/skills/project-memory/skill.vi.md +223 -0
- package/dist/core/templates/skills/seo-audit/skill.md +75 -0
- package/dist/core/templates/skills/seo-audit/skill.vi.md +75 -0
- package/dist/core/templates/skills/seo-audit-skill.md +75 -0
- package/dist/core/templates/skills/seo-audit-skill.vi.md +75 -0
- package/dist/core/templates/skills/smart-explore/skill.md +141 -0
- package/dist/core/templates/skills/sourcecode-analyzer/skill.md +210 -0
- package/dist/core/templates/skills/sourcecode-analyzer/skill.vi.md +210 -0
- package/dist/core/templates/skills/spec-writer/skill.md +61 -0
- package/dist/core/templates/skills/spec-writer/skill.vi.md +61 -0
- package/dist/core/templates/skills/spec-writer-skill.md +61 -0
- package/dist/core/templates/skills/spec-writer-skill.vi.md +61 -0
- package/dist/core/templates/skills/sql-queries/skill.md +67 -0
- package/dist/core/templates/skills/sql-queries/skill.vi.md +67 -0
- package/dist/core/templates/skills/sql-queries-skill.md +67 -0
- package/dist/core/templates/skills/sql-queries-skill.vi.md +67 -0
- package/dist/core/templates/skills/suggestion/skill.md +118 -0
- package/dist/core/templates/skills/system-design/skill.md +70 -0
- package/dist/core/templates/skills/system-design/skill.vi.md +70 -0
- package/dist/core/templates/skills/system-design-skill.md +70 -0
- package/dist/core/templates/skills/system-design-skill.vi.md +70 -0
- package/dist/core/templates/skills/tech-debt/skill.md +70 -0
- package/dist/core/templates/skills/tech-debt/skill.vi.md +70 -0
- package/dist/core/templates/skills/tech-debt-skill.md +70 -0
- package/dist/core/templates/skills/tech-debt-skill.vi.md +70 -0
- package/dist/core/templates/skills/ui-ux/data/charts.csv +26 -0
- package/dist/core/templates/skills/ui-ux/data/colors.csv +97 -0
- package/dist/core/templates/skills/ui-ux/data/design-systems.csv +54 -0
- package/dist/core/templates/skills/ui-ux/data/landing.csv +31 -0
- package/dist/core/templates/skills/ui-ux/data/pages-proposed.csv +22 -0
- package/dist/core/templates/skills/ui-ux/data/pages.csv +10 -0
- package/dist/core/templates/skills/ui-ux/data/products.csv +97 -0
- package/dist/core/templates/skills/ui-ux/data/prompts.csv +24 -0
- package/dist/core/templates/skills/ui-ux/data/stacks/flutter.csv +53 -0
- package/dist/core/templates/skills/ui-ux/data/stacks/html-tailwind.csv +56 -0
- package/dist/core/templates/skills/ui-ux/data/stacks/nextjs.csv +53 -0
- package/dist/core/templates/skills/ui-ux/data/stacks/react-native.csv +52 -0
- package/dist/core/templates/skills/ui-ux/data/stacks/react.csv +54 -0
- package/dist/core/templates/skills/ui-ux/data/stacks/svelte.csv +54 -0
- package/dist/core/templates/skills/ui-ux/data/stacks/swiftui.csv +51 -0
- package/dist/core/templates/skills/ui-ux/data/stacks/vue.csv +50 -0
- package/dist/core/templates/skills/ui-ux/data/styles.csv +59 -0
- package/dist/core/templates/skills/ui-ux/data/typography.csv +58 -0
- package/dist/core/templates/skills/ui-ux/data/ux-guidelines.csv +100 -0
- package/dist/core/templates/skills/ui-ux/scripts/CODE_EXPLANATION.md +394 -0
- package/dist/core/templates/skills/ui-ux/scripts/SEARCH_ALGORITHMS_COMPARISON.md +421 -0
- package/dist/core/templates/skills/ui-ux/scripts/SEARCH_MODES_GUIDE.md +238 -0
- package/dist/core/templates/skills/ui-ux/scripts/core.py +391 -0
- package/dist/core/templates/skills/ui-ux/scripts/search.py +73 -0
- package/dist/core/templates/skills/ui-ux/skill.md +595 -0
- package/dist/core/templates/skills/ui-ux/templates/accessibility-checklist.md +40 -0
- package/dist/core/templates/skills/ui-ux/templates/example-prompt-full-theme.md +333 -0
- package/dist/core/templates/skills/ui-ux/templates/page-types-guide.md +338 -0
- package/dist/core/templates/skills/ui-ux/templates/pages-proposed-summary.md +273 -0
- package/dist/core/templates/skills/ui-ux/templates/pre-delivery-checklist.md +42 -0
- package/dist/core/templates/skills/ui-ux/templates/prompt-template-full-theme.md +313 -0
- package/dist/core/templates/skills/ui-ux/templates/responsive-design.md +40 -0
- package/dist/core/templates/skills/unit-test/skill.md +111 -0
- package/dist/core/templates/skills/wordpress/plugin-check/skill.md +151 -0
- package/dist/core/templates/skills/wordpress/plugin-directory/skill.md +396 -0
- package/dist/core/templates/skills/wordpress/plugin-standard/skill.md +100 -0
- package/dist/core/templates/skills/wordpress/plugin-standard/templates/admin-dashboard.php +47 -0
- package/dist/core/templates/skills/wordpress/plugin-standard/templates/admin-settings.php +60 -0
- package/dist/core/templates/skills/wordpress/plugin-standard/templates/assets/admin-css.css +22 -0
- package/dist/core/templates/skills/wordpress/plugin-standard/templates/assets/admin-js.js +15 -0
- package/dist/core/templates/skills/wordpress/plugin-standard/templates/plugin-main.php +169 -0
- package/dist/core/templates/skills/wordpress/plugin-standard/templates/readme.txt +41 -0
- package/dist/core/templates/skills/wordpress/plugin-standard/templates/uninstall.php +21 -0
- package/dist/core/templates/skills/wordpress/ux-element/skill.md +83 -0
- package/dist/core/templates/skills/wordpress/ux-element/templates/Controller.php +50 -0
- package/dist/core/templates/skills/wordpress/ux-element/templates/Shortcode.php +23 -0
- package/dist/core/templates/skills/wordpress/ux-element/templates/Template.html +20 -0
- package/dist/core/templates/skills/wordpress/ux-element/templates/Thumbnail.svg +8 -0
- package/dist/core/templates/skills/wordpress/ux-element/templates/View.php +21 -0
- package/dist/core/templates/skills-template-map.d.ts +29 -0
- package/dist/core/validation/validator.d.ts +26 -0
- package/dist/core/view.d.ts +4 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.js +350 -114
- package/dist/utils/file-system.d.ts +19 -0
- package/dist/utils/index.d.ts +6 -0
- package/dist/utils/task-parser.d.ts +26 -0
- package/package.json +2 -2
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Kỹ năng: Sửa lỗi (Debugging) (Cross-Cutting)
|
|
2
|
+
|
|
3
|
+
## Mục đích
|
|
4
|
+
|
|
5
|
+
Thực hiện một phiên debug có cấu trúc để tái dựng (reproduce), cô lập (isolate), chẩn đoán (diagnose) và sửa lỗi phần mềm một cách hệ thống.
|
|
6
|
+
|
|
7
|
+
## Khi nào sử dụng
|
|
8
|
+
|
|
9
|
+
- Khi gặp stack trace, biệt lệ thời gian chạy (runtime exception) hoặc thông báo lỗi
|
|
10
|
+
- Khi hành vi của hệ thống khác biệt so với đặc tả kỹ thuật (specs)
|
|
11
|
+
- Khi phát hiện lỗi trên môi trường staging hoặc production nhưng chưa rõ nguyên nhân
|
|
12
|
+
|
|
13
|
+
## Quy trình từng bước
|
|
14
|
+
|
|
15
|
+
### Bước 1: Tái dựng lỗi (Reproduce)
|
|
16
|
+
- Xác định hành vi mong đợi (Expected) vs. hành vi thực tế (Actual)
|
|
17
|
+
- Xác định các bước tối giản để tái dựng lỗi một cách chính xác
|
|
18
|
+
- Đánh giá phạm vi của lỗi (ai bị ảnh hưởng, lỗi bắt đầu từ khi nào)
|
|
19
|
+
|
|
20
|
+
### Bước 2: Cô lập lỗi (Isolate)
|
|
21
|
+
- Thu hẹp phạm vi tìm kiếm vào component, module hoặc luồng code gây lỗi
|
|
22
|
+
- Phân tích log, lỗi đầu ra hoặc lịch sử các commit gần đây
|
|
23
|
+
- Kiểm tra các thay đổi cấu hình hoặc cập nhật thư viện gần đây
|
|
24
|
+
|
|
25
|
+
### Bước 3: Chẩn đoán lỗi (Diagnose)
|
|
26
|
+
- Đưa ra giả thuyết có thể kiểm chứng và trace luồng dữ liệu/biến số
|
|
27
|
+
- Xác định nguyên nhân gốc rễ (root cause) thay vì chỉ xử lý triệu chứng bề nổi
|
|
28
|
+
|
|
29
|
+
### Bước 4: Sửa lỗi & Ngăn ngừa (Fix & Prevent)
|
|
30
|
+
- Đề xuất và triển khai giải pháp sửa lỗi code chính xác
|
|
31
|
+
- Phân tích các tác dụng phụ và trường hợp biên phát sinh từ bản sửa lỗi
|
|
32
|
+
- Xây dựng chiến lược test hồi quy (regression tests) để ngăn ngừa lỗi lặp lại
|
|
33
|
+
|
|
34
|
+
## Input yêu cầu
|
|
35
|
+
|
|
36
|
+
- Thông báo lỗi, stack trace hoặc mô tả chi tiết lỗi
|
|
37
|
+
- Các bước tái dựng lỗi (hoặc thông tin môi trường chạy thử)
|
|
38
|
+
- Quyền truy cập vào file log hoặc các component liên quan
|
|
39
|
+
|
|
40
|
+
## Output mong đợi
|
|
41
|
+
|
|
42
|
+
- Báo cáo sửa lỗi (Debug Report) bao gồm:
|
|
43
|
+
- Tái dựng lỗi (Mong đợi vs. Thực tế)
|
|
44
|
+
- Phân tích nguyên nhân gốc rễ (Root Cause)
|
|
45
|
+
- Giải pháp sửa lỗi đã áp dụng
|
|
46
|
+
- Kế hoạch ngăn ngừa (test hồi quy cần bổ sung)
|
|
47
|
+
|
|
48
|
+
## Giọng điệu & Quy tắc
|
|
49
|
+
|
|
50
|
+
- Thực hiện debug một cách hệ thống. Không đoán mò giải pháp một cách mù quáng.
|
|
51
|
+
- Tài liệu hóa các ràng buộc của code và lý do tại sao giải pháp sửa lỗi hoạt động hiệu quả.
|
|
52
|
+
- Tập trung vào bản sửa lỗi; tránh refactor các phần code không liên quan trong khi sửa lỗi.
|
|
53
|
+
|
|
54
|
+
## Templates có sẵn
|
|
55
|
+
|
|
56
|
+
- Không có
|
|
57
|
+
|
|
58
|
+
## Scripts có sẵn
|
|
59
|
+
|
|
60
|
+
- Không có
|
|
61
|
+
|
|
62
|
+
## Ví dụ
|
|
63
|
+
|
|
64
|
+
Xem thư mục `examples/`.
|
|
65
|
+
|
|
66
|
+
## Liên kết với các kỹ năng khác
|
|
67
|
+
|
|
68
|
+
- **unit-test**: Dùng để viết test hồi quy cho lỗi vừa sửa.
|
|
69
|
+
- **project-memory**: Dùng để tìm kiếm các bản sửa lỗi lịch sử hoặc vấn đề liên quan.
|
|
@@ -0,0 +1,408 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deploy-documentation
|
|
3
|
+
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.
|
|
4
|
+
projectType: all
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Deploy Documentation — Auto Screenshot & Docs Generator
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
**Vấn đề giải quyết:**
|
|
14
|
+
- Sau khi build xong plugin/module/software, developer phải truy cập từng trang tính năng trên site
|
|
15
|
+
- Chụp ảnh thủ công, dễ sai sót (quên cập nhật mô tả)
|
|
16
|
+
- Tốn thời gian khi có nhiều route, lặp lại mỗi version
|
|
17
|
+
|
|
18
|
+
## When to Use
|
|
19
|
+
|
|
20
|
+
- Sau mỗi lần release / deploy phiên bản mới
|
|
21
|
+
- Khi cần sync documentation screenshots với UI thực tế
|
|
22
|
+
- Khi thêm tính năng mới chưa có trong manifest
|
|
23
|
+
- Khi cần chụp ảnh từ nhiều site khác nhau (local, demo, client)
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Architecture: 2 Phases
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
Phase 1: DISCOVER — Quét codebase → Suggest manifest entries
|
|
31
|
+
Phase 2: CAPTURE — Đọc manifest → Login → Navigate → Screenshot → Update HTML
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Phase 1: Route Discovery & Manifest Generation
|
|
37
|
+
|
|
38
|
+
### Mục đích
|
|
39
|
+
Tự động quét codebase để phát hiện routes/pages, sau đó suggest thêm entries vào `deploy_manifest.json`.
|
|
40
|
+
|
|
41
|
+
### Cách hoạt động
|
|
42
|
+
|
|
43
|
+
**1. Quét routes — tìm tất cả route definitions trong codebase:**
|
|
44
|
+
|
|
45
|
+
| Project Type | Source files |
|
|
46
|
+
|---|---|
|
|
47
|
+
| Perfex CRM Module | `config/my_routes.php` + controller method names |
|
|
48
|
+
| Laravel App | `routes/web.php`, `routes/api.php` |
|
|
49
|
+
| WordPress Plugin | `add_menu_page()`, `add_submenu_page()` hooks |
|
|
50
|
+
| Next.js / Vite SPA | `pages/` directory, router config files |
|
|
51
|
+
| Electron App | Window/view registrations |
|
|
52
|
+
| Generic | Navigation config files, sitemap |
|
|
53
|
+
|
|
54
|
+
**2. Quét menu registrations — tìm sidebar/nav menu items:**
|
|
55
|
+
- Perfex CRM: `$this->app_menu->add_sidebar_menu_item()` calls
|
|
56
|
+
- WordPress: `add_menu_page()`, `add_submenu_page()`
|
|
57
|
+
- Generic: tìm navigation config files
|
|
58
|
+
|
|
59
|
+
**3. Quét migration changelog:**
|
|
60
|
+
- Parse `logChanged()` hoặc `CHANGELOG.md` để detect features mới chưa có trong manifest
|
|
61
|
+
|
|
62
|
+
**4. Cross-reference với manifest:**
|
|
63
|
+
- So sánh routes discovered vs entries đã khai báo → suggest entries còn thiếu
|
|
64
|
+
|
|
65
|
+
### Discovery Scan Targets (Perfex CRM modules — example)
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
modules/{module}/config/my_routes.php → Route definitions
|
|
69
|
+
modules/{module}/data_builder.php → Menu items (add_sidebar_menu_item)
|
|
70
|
+
modules/{module}/controllers/*.php → Controller methods = pages
|
|
71
|
+
modules/{module}/views/admin/**/*.php → View templates
|
|
72
|
+
modules/{module}/migrations/*_version_*.php → Changelog (logChanged)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Output Format — Suggested Entry
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"id": "auto-discovered-{route}",
|
|
80
|
+
"filename": "{Feature-Name}-{Product}.png",
|
|
81
|
+
"title": "{Feature Name}",
|
|
82
|
+
"route": "/admin/{module}/{controller}/{method}",
|
|
83
|
+
"wait_for": "#app, .panel, .table-responsive",
|
|
84
|
+
"section": "core-features",
|
|
85
|
+
"actions_before": [
|
|
86
|
+
{ "action": "wait", "ms": 2000 }
|
|
87
|
+
],
|
|
88
|
+
"_discovered_from": "controller: Builder.php → method: index()",
|
|
89
|
+
"_status": "suggested"
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
> **IMPORTANT**: Entries có `_status: "suggested"` cần user review và confirm trước khi chạy Phase 2. Agent MUST NOT auto-proceed.
|
|
94
|
+
|
|
95
|
+
### Site Suggestion Logic (khi discover)
|
|
96
|
+
|
|
97
|
+
| Loại page | Site đề xuất | Lý do |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| Admin management pages | `local` | Không cần real data |
|
|
100
|
+
| Charts, runtime reports | `demo` | Cần data đẹp, trực quan |
|
|
101
|
+
| Public embed / iframe | `demo` | Cần public view đã setup |
|
|
102
|
+
| Client-specific feature | `client_x` | Cần data thực tế của client |
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Phase 2: Screenshot Capture & Documentation Update
|
|
107
|
+
|
|
108
|
+
### Prerequisites
|
|
109
|
+
- File `deploy_manifest.json` đã được review và xác nhận
|
|
110
|
+
- Site đang chạy và accessible tại `base_url`
|
|
111
|
+
- Credentials hợp lệ
|
|
112
|
+
|
|
113
|
+
### Step 1: Build Site Groups
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
1. Đọc manifest.sites{} và manifest.default_site
|
|
117
|
+
2. Với mỗi entry trong screenshots[]:
|
|
118
|
+
- Nếu entry có "site" key → site = sites[entry.site]
|
|
119
|
+
- Nếu không → site = sites[default_site]
|
|
120
|
+
3. Group entries by site key → { local: [...], demo: [...], client_x: [...] }
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Step 2: Login (một lần mỗi site)
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
Foreach unique_site in groups:
|
|
127
|
+
site_config = sites[unique_site]
|
|
128
|
+
1. Mở browser tab mới tại: {site_config.base_url}{site_config.login_url}
|
|
129
|
+
2. Điền credentials:
|
|
130
|
+
- email_selector ← site_config.login_form.email_selector
|
|
131
|
+
- password_selector ← site_config.login_form.password_selector
|
|
132
|
+
3. Click submit: site_config.login_form.submit_selector
|
|
133
|
+
4. Chờ redirect hoặc dashboard element xuất hiện
|
|
134
|
+
5. Lưu session/cookies cho site này
|
|
135
|
+
Log: ✅ Logged in to {site_config.base_url} / ❌ Login failed
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**login_form supports:**
|
|
139
|
+
- Perfex CRM: `input[name='email']` + `input[name='password']`
|
|
140
|
+
- WordPress: `input#user_login` + `input#user_pass`
|
|
141
|
+
- Laravel / generic: any valid CSS selector
|
|
142
|
+
|
|
143
|
+
### Step 3: Screenshot Loop
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
Foreach entry in manifest.screenshots[]:
|
|
147
|
+
site_config = sites[entry.site || default_site]
|
|
148
|
+
base_url = site_config.base_url
|
|
149
|
+
|
|
150
|
+
1. Navigate tới {base_url}{entry.route}
|
|
151
|
+
Resolve dynamic tokens nếu có:
|
|
152
|
+
{first_view_id} → Scrape view list page → first row ID
|
|
153
|
+
{first_view_route} → Scrape view list page → first row route slug
|
|
154
|
+
{first_public_route} → Scrape views → first with public_access indicator
|
|
155
|
+
{latest_record_id} → Scrape or sort by date → most recent ID
|
|
156
|
+
|
|
157
|
+
2. Set viewport: entry.viewport || manifest.defaults.viewport
|
|
158
|
+
|
|
159
|
+
3. Execute actions_before[] theo thứ tự:
|
|
160
|
+
wait → sleep(ms)
|
|
161
|
+
click → click(selector)
|
|
162
|
+
click_first_visible → find first visible element → click
|
|
163
|
+
scroll_down → window.scrollBy(0, px)
|
|
164
|
+
scroll_to → element.scrollIntoView()
|
|
165
|
+
type → type text into selector (for search/filter inputs)
|
|
166
|
+
|
|
167
|
+
4. Wait for: entry.wait_for selector to appear in DOM
|
|
168
|
+
|
|
169
|
+
5. Capture screenshot:
|
|
170
|
+
format = entry.format || manifest.defaults.format
|
|
171
|
+
Save → {output.images_dir}/{entry.filename}
|
|
172
|
+
|
|
173
|
+
Log: ✅ {entry.id} → {entry.filename} / ❌ reason
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Step 4: HTML Update (Optional)
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
1. Đọc index.html
|
|
180
|
+
2. Cập nhật version number từ source code
|
|
181
|
+
3. Cập nhật date (Updated: {current month year})
|
|
182
|
+
4. Parse changelog từ migration file → inject vào #changelog-content
|
|
183
|
+
5. Verify tất cả <img src="images/..."> đều có file tương ứng
|
|
184
|
+
6. Save index.html
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Manifest Format Reference
|
|
190
|
+
|
|
191
|
+
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:
|
|
192
|
+
|
|
193
|
+
```json
|
|
194
|
+
{
|
|
195
|
+
"product": {
|
|
196
|
+
"name": "Product Name",
|
|
197
|
+
"tagline": "Short description",
|
|
198
|
+
"version_source": "path/to/version_file",
|
|
199
|
+
"changelog_source": "path/to/migration_or_changelog"
|
|
200
|
+
},
|
|
201
|
+
|
|
202
|
+
"sites": {
|
|
203
|
+
"local": {
|
|
204
|
+
"base_url": "https://localhost:PORT",
|
|
205
|
+
"login_url": "/admin/authentication",
|
|
206
|
+
"login_form": {
|
|
207
|
+
"email_selector": "input[name='email']",
|
|
208
|
+
"password_selector": "input[name='password']",
|
|
209
|
+
"submit_selector": "button[type='submit']"
|
|
210
|
+
},
|
|
211
|
+
"credentials": {
|
|
212
|
+
"email": "admin@admin.com",
|
|
213
|
+
"password": "password"
|
|
214
|
+
},
|
|
215
|
+
"description": "Local dev"
|
|
216
|
+
},
|
|
217
|
+
"demo": {
|
|
218
|
+
"base_url": "https://demo.example.com",
|
|
219
|
+
"login_url": "/admin/authentication",
|
|
220
|
+
"login_form": {
|
|
221
|
+
"email_selector": "input[name='email']",
|
|
222
|
+
"password_selector": "input[name='password']",
|
|
223
|
+
"submit_selector": "button[type='submit']"
|
|
224
|
+
},
|
|
225
|
+
"credentials": {
|
|
226
|
+
"email": "admin@demo.com",
|
|
227
|
+
"password": "password"
|
|
228
|
+
},
|
|
229
|
+
"description": "Live demo site for marketing screenshots"
|
|
230
|
+
}
|
|
231
|
+
},
|
|
232
|
+
|
|
233
|
+
"default_site": "local",
|
|
234
|
+
|
|
235
|
+
"output": {
|
|
236
|
+
"images_dir": "path/to/documentation/images",
|
|
237
|
+
"html_file": "path/to/documentation/index.html"
|
|
238
|
+
},
|
|
239
|
+
|
|
240
|
+
"defaults": {
|
|
241
|
+
"viewport": { "width": 1440, "height": 900 },
|
|
242
|
+
"format": "png",
|
|
243
|
+
"wait_ms": 2000
|
|
244
|
+
},
|
|
245
|
+
|
|
246
|
+
"screenshots": [
|
|
247
|
+
{
|
|
248
|
+
"id": "feature-overview",
|
|
249
|
+
"filename": "Feature-Overview-ProductName.png",
|
|
250
|
+
"title": "Feature Overview",
|
|
251
|
+
"route": "/admin/module/page",
|
|
252
|
+
"wait_for": "#app, .panel, .table-responsive",
|
|
253
|
+
"section": "core-features",
|
|
254
|
+
"actions_before": [
|
|
255
|
+
{ "action": "wait", "ms": 2000 }
|
|
256
|
+
]
|
|
257
|
+
},
|
|
258
|
+
{
|
|
259
|
+
"id": "feature-on-demo",
|
|
260
|
+
"site": "demo",
|
|
261
|
+
"filename": "Feature-Demo-ProductName.png",
|
|
262
|
+
"title": "Feature (Demo Data)",
|
|
263
|
+
"route": "/admin/module/page",
|
|
264
|
+
"wait_for": ".chart-container",
|
|
265
|
+
"section": "core-features",
|
|
266
|
+
"actions_before": [
|
|
267
|
+
{ "action": "wait", "ms": 3000 }
|
|
268
|
+
]
|
|
269
|
+
}
|
|
270
|
+
]
|
|
271
|
+
}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### Dynamic Route Tokens
|
|
275
|
+
|
|
276
|
+
| Token | Resolution |
|
|
277
|
+
|-------|-----------|
|
|
278
|
+
| `{first_view_id}` | ID của record đầu tiên trong view list |
|
|
279
|
+
| `{first_view_route}` | Route slug của view đầu tiên |
|
|
280
|
+
| `{first_public_route}` | Route của view public đầu tiên |
|
|
281
|
+
| `{latest_record_id}` | ID của record mới nhất |
|
|
282
|
+
|
|
283
|
+
Agent resolves các token này bằng cách scrape trang list hoặc query database.
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
## Prompt Templates
|
|
288
|
+
|
|
289
|
+
### Full workflow (Discover + Capture):
|
|
290
|
+
|
|
291
|
+
```
|
|
292
|
+
Sử dụng skill deploy-documentation.
|
|
293
|
+
Project: {module_path}
|
|
294
|
+
Manifest: {manifest_path}
|
|
295
|
+
|
|
296
|
+
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)
|
|
297
|
+
2. Tôi sẽ review và confirm manifest
|
|
298
|
+
3. Phase 2: Login vào từng site trong manifest, chụp tất cả screenshots, lưu vào images_dir
|
|
299
|
+
4. Cập nhật index.html với ảnh mới và changelog
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### Chỉ chụp ảnh — tất cả sites (manifest đã sẵn):
|
|
303
|
+
|
|
304
|
+
```
|
|
305
|
+
Sử dụng skill deploy-documentation.
|
|
306
|
+
Đọc manifest tại {manifest_path}.
|
|
307
|
+
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.
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
### Chỉ chụp ảnh — 1 site cụ thể:
|
|
311
|
+
|
|
312
|
+
```
|
|
313
|
+
Sử dụng skill deploy-documentation.
|
|
314
|
+
Đọc manifest tại {manifest_path}.
|
|
315
|
+
Chỉ chụp các screenshots thuộc site "demo".
|
|
316
|
+
Login vào demo site, navigate và capture, lưu vào images_dir.
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
### Chỉ chụp lại 1 số ảnh cụ thể:
|
|
320
|
+
|
|
321
|
+
```
|
|
322
|
+
Sử dụng skill deploy-documentation.
|
|
323
|
+
Đọc manifest tại {manifest_path}.
|
|
324
|
+
Chỉ chụp lại các entries: {id1}, {id2}, {id3}.
|
|
325
|
+
Sử dụng site mặc định (default_site) trừ khi entry có khai báo site riêng.
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
### Chỉ discover — suggest entries mới:
|
|
329
|
+
|
|
330
|
+
```
|
|
331
|
+
Sử dụng skill deploy-documentation.
|
|
332
|
+
Quét codebase tại {module_path}, so sánh với manifest tại {manifest_path}.
|
|
333
|
+
Suggest entries mới cho features/routes chưa được khai báo.
|
|
334
|
+
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).
|
|
335
|
+
Không tự thêm vào manifest — liệt kê để tôi review trước.
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Compatibility — Supported Project Types
|
|
341
|
+
|
|
342
|
+
| Project Type | Route Discovery Source |
|
|
343
|
+
|---|---|
|
|
344
|
+
| Perfex CRM Module | `my_routes.php` + controller methods |
|
|
345
|
+
| Laravel App | `routes/web.php` + `routes/api.php` |
|
|
346
|
+
| WordPress Plugin | `add_menu_page()` + `add_submenu_page()` |
|
|
347
|
+
| Next.js / Vite SPA | `pages/` directory + router config |
|
|
348
|
+
| Electron App | Window/view registrations |
|
|
349
|
+
| Generic Web App | Navigation config files, sitemap |
|
|
350
|
+
|
|
351
|
+
Mỗi project chỉ cần 1 file `deploy_manifest.json` riêng. Cùng skill, cùng workflow.
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
|
|
355
|
+
## File Structure (per project/module)
|
|
356
|
+
|
|
357
|
+
`deploy_manifest.json` nằm **cùng folder với `AGENTS.heraspec.md` và `heraspec/`** của module/project đó:
|
|
358
|
+
|
|
359
|
+
```
|
|
360
|
+
{heraspec_workspace_dir}/ ← Thư mục chứa AGENTS.heraspec.md
|
|
361
|
+
├── AGENTS.heraspec.md
|
|
362
|
+
├── heraspec/
|
|
363
|
+
├── deploy_manifest.json ← Đặt tại đây
|
|
364
|
+
└── documentation/
|
|
365
|
+
├── index.html
|
|
366
|
+
└── images/
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
**Ví dụ với Perfex CRM** (mỗi module là một workspace HeraSpec riêng):
|
|
370
|
+
|
|
371
|
+
```
|
|
372
|
+
perfex_crm/
|
|
373
|
+
└── modules/
|
|
374
|
+
├── data_builder/
|
|
375
|
+
│ ├── AGENTS.heraspec.md
|
|
376
|
+
│ ├── heraspec/
|
|
377
|
+
│ ├── deploy_manifest.json ← manifest của data_builder
|
|
378
|
+
│ └── documentation/
|
|
379
|
+
└── another_module/
|
|
380
|
+
├── AGENTS.heraspec.md
|
|
381
|
+
├── heraspec/
|
|
382
|
+
├── deploy_manifest.json ← manifest riêng của another_module
|
|
383
|
+
└── documentation/
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
> **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.
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
---
|
|
390
|
+
|
|
391
|
+
## Inputs
|
|
392
|
+
|
|
393
|
+
- `deploy_manifest.json` — manifest file của project (xem templates/deploy_manifest.template.json)
|
|
394
|
+
- Codebase path — để Phase 1 discover routes
|
|
395
|
+
- Running site — để Phase 2 capture screenshots
|
|
396
|
+
|
|
397
|
+
## Outputs
|
|
398
|
+
|
|
399
|
+
- Screenshot PNG/WebP files tại `output.images_dir`
|
|
400
|
+
- Updated `index.html` tại `output.html_file`
|
|
401
|
+
- Suggested entries (Phase 1 only) — danh sách để user review
|
|
402
|
+
|
|
403
|
+
## Limitations
|
|
404
|
+
|
|
405
|
+
- Yêu cầu browser agent có khả năng điều khiển browser (navigate, click, screenshot)
|
|
406
|
+
- Login session không persistent giữa các lần chạy — phải login lại mỗi session
|
|
407
|
+
- Dynamic tokens (`{first_view_id}`, v.v.) cần site đang có dữ liệu thực
|
|
408
|
+
- 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)
|