@relipa/ai-flow-kit 0.1.2 → 0.1.4-beta.0

package/README.md

@@ -70,6 +70,82 @@ PM writes ticket on Backlog/Jira
 
 ---
 
+## Execute Test Flow
+
+```
+aiflow execute PROJ-44  (or ./testcases.md  or  aiflow execute)
+        │
+        ▼
+⛩️ GATE 1 — Pre-flight & Work Plan           [AI + QA]
+  Parse TC file → verify ak-test/{repo}/ exists
+  Check BASE_URL env var + playwright.config.ts
+  Create execution work plan
+        │ Ready
+        ▼
+⛩️ GATE 2 — Script Sync                      [AI]
+  Hash-based TC↔script sync
+  Generate new / update changed / skip unchanged
+  Uses Playwright MCP for selectors — never fabricates
+        │ Scripts synced
+        ▼
+⛩️ GATE 3 — Execute & Evidence               [AI]
+  Run: npx playwright test
+  Organize evidence per run-{N}/: screenshots, trace.zip, result.md
+  Auto-draft bug files for failed TCs
+  Support RETEST: [TC_ID] loop
+        │ Tests done
+        ▼
+⛩️ GATE 4 — Report & Bug Logging             [AI + QA]
+  Generate testreport.md with Go/No-Go recommendation
+  Log each failed TC to Jira/Backlog — interactive confirm per bug
+        │
+        ▼
+       DONE
+```
+
+---
+
+## Execute Test Flow
+
+Flow độc lập cho QA — không cần chạy lại phân tích (Gates 1–2 của Development Flow).
+
+```
+QA nhận TC file (từ ticket hoặc file)
+        │
+        ▼
+⛩️ GATE 1 — Context & Work Plan              [AI + QA]
+  aiflow execute PROJ-44   →   claude
+  AI kiểm tra: MCP Playwright, ak-test/, BASE_URL, playwright.config.ts
+  AI parse TC file → extract TCs, phân loại Auto / Manual
+  AI xuất work plan + danh sách TCs cần thực thi
+        │ Work Plan ready
+        ▼
+⛩️ GATE 2 — Script Sync                      [AI]
+  Hash-based TC ↔ script sync
+  Gen mới TC chưa có script (Playwright MCP → selector DOM thật)
+  Cập nhật script đã thay đổi, bỏ qua script không đổi
+  Không fabricate selector — luôn lấy từ DOM thật
+        │ Scripts synced
+        ▼
+⛩️ GATE 3 — Execute & Evidence               [AI]
+  Chạy Playwright, tổ chức evidence theo run-{N}/
+  Cập nhật cột R1/R2 trong TC file
+  Tổng hợp kết quả pass/fail per TC
+        │ Tests done
+        ▼
+⛩️ GATE 4 — Report & Bug Logging             [AI + QA]
+  AI tạo: testreport.md
+  AI hỏi từng bug → QA xác nhận log lên Jira/Backlog
+  QA review → DONE
+        │
+        ▼
+       DONE
+```
+
+> **Entry points:** `aiflow execute PROJ-44` (từ ticket) · `aiflow execute ./testcases/AD10.md` (từ file) · `aiflow execute` (manual — AI hỏi TC file path)
+
+---
+
 ## Installation
 
 ```bash
@@ -91,6 +167,7 @@ npm uninstall -g @relipa/ai-flow-kit
 |---------|-------------|
 | `aiflow init` | Setup framework, adapters, and multi-AI rules. |
 | `aiflow use <ticket...>` | Load context from one or more tickets/files. First target is primary; rest become supplementary. |
+| `aiflow execute <target>` | **QA:** Execute test cases — load TC file, sync Playwright scripts, run and collect evidence. |
 | `aiflow fetch-links <url>` | Fetch a Backlog/Jira link and print SupplementaryContext JSON (used by AI at runtime). |
 | `aiflow task` | Manage multiple tasks — pause, switch, resume. |
 | `aiflow task next` | Finalize gate approval and prepare for fresh session. |
@@ -141,6 +218,31 @@ aiflow init --framework spring-boot,reactjs --adapter backlog,jira
 
 ---
 
+### `aiflow execute <target>`
+
+Execute test cases from a Backlog/Jira ticket, a TC file, or manually. The AI syncs Playwright scripts, runs them, collects evidence, and generates a test report.
+
+```bash
+# From a ticket (taskType must be "execute")
+aiflow execute PROJ-44
+
+# From a TC file directly
+aiflow execute ./testcases/AD10.md
+
+# Manual — AI asks for TC file path
+aiflow execute
+```
+
+**What happens (4-gate Execute Flow):**
+1. **Gate 1 — Pre-flight:** Parse TC file, verify `ak-test/{repo}/` exists, check `BASE_URL` and `playwright.config.ts`
+2. **Gate 2 — Script Sync:** Hash-based TC↔script sync — gen new, update changed, skip unchanged (never fabricates selectors — uses Playwright MCP)
+3. **Gate 3 — Execute & Evidence:** Run Playwright, organize evidence per `run-{N}/`, update TC file R1/R2 columns
+4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md`, ask per-bug Jira confirmation
+
+> **Multi-AI:** Works with Claude, Gemini, Cursor, Copilot — the execute-flow skill is loaded via `ak init`/`ak up`.
+
+---
+
 ### `aiflow sync-skills`
 
 Synchronize AI instruction files (`CLAUDE.md`, `GEMINI.md`, etc.) and Skills without upgrading the package version. 
@@ -428,6 +530,43 @@ Then run `aiflow update` or `aiflow sync-skills` to apply.
 
 > Summary of major changes per version. See full details in [CHANGELOG.md](docs/common/CHANGELOG.md).
 
+### v0.1.3 — 2026-06-18
+- **Execute Test Flow (4-Gate):** New `aiflow execute` command + `execute-flow` skill — Pre-flight → Script Sync → Execute & Evidence → Report & Bug Logging.
+- **`script-sync` skill:** Hash-based TC↔Playwright script sync — gen new, update changed, skip unchanged. Uses MCP browser tools for selectors, never fabricates.
+- **`ak execute` command** (`ak ex` alias): Standalone QA entry point — accepts ticket ID, TC file path, or interactive mode.
+- **▶️ Execute Test** added to `ak use` type selector; `taskType: "execute"` routes AI to execute-flow skill automatically.
+- **Playwright harness scaffold** (`ak scaffold playwright`): Creates full `ak-test/{repo}/` structure with config, fixtures, and page objects.
+- Fixes: `screenId` casing ambiguity, `--reporter` flag overriding config reporters, Gate 1 missing `playwright.config.ts` check.
+
+### v0.1.2 — 2026-06-13
+- **Testing Workflow (4-Gate):** New `taskType: "testing"` — Test Analysis → Test Planning → Test Execution → Test Report. AI auto-routes skill per gate.
+- **`python-ml` framework:** Supports scikit-learn / PyTorch / TensorFlow / MLflow / Wandb. Auto-detected from `requirements.txt` / `pyproject.toml`.
+- **Task type selector in `ak use`:** Interactive list after loading ticket — auto-detects and pre-selects task type.
+- **Critical fix — `update`/`init` not updating CLAUDE.md/GEMINI.md:** Fixed 3 compounding causes (`framework` singular vs. plural, missing `force: true`, per-file confirm dialogs).
+- **Backup before overwrite:** AI instruction files backed up to `.aiflow/bk/YYYY-MM-DD_HH-MM_<filename>` before any overwrite.
+- **`aiflow update` no longer wipes `.claude/`:** Now clears only `.claude/skills/`, preserving `settings.json` and hooks.
+
+### v0.1.1 — 2026-06-08
+- **Ubuntu/Linux clipboard in `ak prompt`:** Auto-detects display server (Wayland/X11) and package manager — offers to install clipboard tool if missing.
+- **`figma-to-component` image detection & export:** Scans node tree for image nodes, exports to `public/assets/figma/`, renders with `<Image>`/`<img>`.
+- **`figma-to-component` MCP pre-check (Step 0):** Verifies MCP connected before running; stops with setup instructions if not.
+- **`figma-to-component` CSS tooling detection:** Branches on Tailwind / CSS Modules / styled-components / vanilla CSS; maps Figma Styles/Variables to existing tokens.
+- **Critical fix — `figma-to-component` source/installed divergence:** Synced both copies to canonical version with correct tool names and 4-tier framework detection.
+
+### v0.1.3 — 2026-06-22
+
+**QA Automation Suite — End-to-end test execution với Playwright MCP**
+
+- New `aiflow execute` command with full 4-gate Execute Flow (pre-flight → script sync → run → report).
+- New skill suite for QA: `execute-flow`, `automation-testing`, `script-sync`, `generate-testcase`, `generate-test-report`, `log-bug`, `test-analysis`, `evidence-aggregation`, `retest-orchestration`, `coverage-check`.
+- Playwright harness template (`custom/harness/playwright/`) — pre-wired `playwright.config.ts`, `BasePage`, fixtures, và auth setup.
+- New `aiflow scaffold` command (`ak sc`) — tự động tạo cấu trúc `ak-test/{repo}/` từ template.
+- Hash-based TC↔script sync: chỉ gen/update script khi TC thay đổi, bỏ qua TC không đổi — không mất thời gian re-gen.
+- Selector lấy từ DOM thật qua Playwright MCP — không fabricate, không đoán.
+- ML framework support: `python-ml` template + 7 ML skills (`frame-ml-problem`, `explore-data`, `design-experiment`, `train-model`, `evaluate-model`, `improve-algorithm`, `deploy-model`).
+- New `pr-impact-analysis` skill — phân tích breaking changes của PR trước khi merge.
+- Deprecated `aiflow` CLI alias — dùng `ak` thay thế (warning hiện khi dùng `aiflow`).
+
 ### v0.1.0 — 2026-05-28
 - Multi-target `ak use` — load multiple tickets/files in a single call (primary + supplementary).
 - Auto link resolution — auto-fetch Backlog/Jira URLs found in the ticket description (capped at 5 links).

package/bin/aiflow.js

@@ -19,6 +19,7 @@ const taskCommand     = require('../scripts/task');
 const checkpointCommand = require('../scripts/checkpoint');
 const { record }      = require('../scripts/telemetry/record');
 const { updateTaskGateState } = require('../scripts/task');
+const scaffoldPlaywrightCommand = require('../scripts/scaffold-playwright');
 const semver = require('semver');
 const { execSync: execSyncChild, spawnSync } = require('child_process');
 
@@ -63,7 +64,8 @@ program
             'up': 'update',
             'sync': 'sync-skills',
             'dr': 'doctor',
-            'tel': 'telemetry'
+            'tel': 'telemetry',
+            'sc': 'scaffold'
         };
         if (aliases[first]) {
             first = aliases[first];
@@ -501,6 +503,53 @@ program
         }
     });
 
+// ── review ────────────────────────────────────────────────────
+const reviewCmd = program.command('review').description('Gate review file operations');
+
+reviewCmd
+    .command('check')
+    .description('Check review file state — called by AI before accepting APPROVED')
+    .requiredOption('-g, --gate <n>', 'gate number (string — supports sub-phases like 2a, 2b)')
+    .requiredOption('-t, --ticket <id>', 'ticket ID')
+    .action(async (opts) => {
+        const { checkReviewFile } = require('../scripts/review');
+        const result = await checkReviewFile(opts.gate, opts.ticket);
+
+        if (!result.exists) {
+            console.log(chalk.red(`\n  ✗ Review file not found for gate ${opts.gate}, ticket ${opts.ticket}`));
+            console.log(chalk.gray(`  Expected: .aiflow/review/gate-${opts.gate}-${opts.ticket}.md`));
+            console.log(chalk.yellow('  → Re-generate the review file before accepting APPROVED.\n'));
+            process.exit(1);
+        }
+
+        if (result.passed) {
+            console.log(chalk.green(`\n  ✅ All ${result.total} items checked — gate can proceed\n`));
+            process.exit(0);
+        }
+
+        const pendingCount = result.unchecked.length + result.commented.length;
+        console.log(chalk.red(`\n  ❌ Review incomplete — ${pendingCount} item(s) pending:\n`));
+
+        if (result.commented.length > 0) {
+            console.log(chalk.yellow('  Items with comments (need AI revision):'));
+            result.commented.forEach(({ item, comment }) => {
+                console.log(chalk.yellow(`    • ${item}`));
+                console.log(chalk.gray(`      Comment: "${comment}"`));
+            });
+            if (result.unchecked.length > 0) console.log('');
+        }
+
+        if (result.unchecked.length > 0) {
+            console.log(chalk.red('  Items unchecked (no comment — please check or add a comment):'));
+            result.unchecked.forEach(item => {
+                console.log(chalk.red(`    • ${item}`));
+            });
+        }
+
+        console.log(chalk.gray('\n  → Check all items in the review file, then type APPROVED again.\n'));
+        process.exit(1);
+    });
+
 // ── remove ────────────────────────────────────────────────────
 program
     .command('remove')
@@ -529,7 +578,7 @@ program
     .description('Manually synchronize AI Instruction files with local custom skills')
     .action(async () => {
         const projectDir = process.cwd();
-        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
+        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored, setupClaudeCommands } = require('../scripts/init');
         const fs = require('fs-extra');
         const path = require('path');
         const chalk = require('chalk');
@@ -549,6 +598,7 @@ program
         for (const fw of frameworks) {
             await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools, { force: true });
         }
+        await setupClaudeCommands(projectDir);
         await ensureAiflowGitignored(projectDir);
         console.log(chalk.green('✨ Sync completed!'));
     });
@@ -575,4 +625,41 @@ program
         telemetryCommand(action || 'status', options);
     });
 
+// ── scaffold ──────────────────────────────────────────────────
+const scaffoldCmd = program.command('scaffold').alias('sc').description('Scaffold project harness files');
+
+scaffoldCmd
+    .command('playwright')
+    .alias('pw')
+    .description('Scaffold Playwright E2E harness (playwright.config.ts, BasePage, fixtures, auth, .mcp.json)')
+    .option('-f, --force', 'overwrite existing files')
+    .option('-d, --dir <path>', 'target directory (default: current directory)')
+    .addHelpText('after', `
+Examples:
+  $ ak scaffold playwright                  Scaffold into current directory
+  $ ak scaffold playwright --force          Overwrite existing files
+  $ ak scaffold playwright --dir ./my-app   Scaffold into ./my-app
+
+Next steps after scaffolding:
+  1. npm install --save-dev @playwright/test
+  2. npx playwright install chromium
+  3. cp .env.example .env  # then fill in BASE_URL
+  4. npx playwright test
+`)
+    .action(async (options) => {
+        const targetDir = options.dir ? require('path').resolve(options.dir) : process.cwd();
+        console.log(chalk.cyan('\n⟳ Scaffolding Playwright E2E harness...\n'));
+        const result = await scaffoldPlaywrightCommand.scaffoldPlaywright(targetDir, { force: !!options.force });
+        console.log(chalk.cyan('\n📦 Next steps:'));
+        console.log(chalk.gray('  1. npm install --save-dev @playwright/test'));
+        console.log(chalk.gray('  2. npx playwright install chromium'));
+        console.log(chalk.gray('  3. cp .env.example .env  # then fill in BASE_URL'));
+        console.log(chalk.gray('  4. npx playwright test'));
+        if (result.copied.length === 0 && result.skipped.length > 0) {
+            console.log(chalk.yellow('\n  ⚠ All files already exist. Use --force to overwrite.\n'));
+        } else {
+            console.log(chalk.green('\n✨ Scaffold complete!\n'));
+        }
+    });
+
 program.parse(process.argv);

package/custom/harness/playwright/.env.example

@@ -0,0 +1,10 @@
+# Sao chép thành .env rồi điền giá trị. KHÔNG commit .env (đã .gitignore).
+
+BASE_URL=http://localhost:3000
+
+# --- Đăng nhập — chỉ cần khi app yêu cầu login ---
+# Có E2E_USER → auth tự bật: đăng nhập 1 lần, lưu phiên, các test tái dùng.
+E2E_USER=
+E2E_PASSWORD=
+E2E_LOGIN_PATH=/login
+E2E_POST_LOGIN_PATH=/dashboard

package/custom/harness/playwright/playwright.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig, devices } from '@playwright/test';
+
+try { require('dotenv').config(); } catch (_) {}
+
+const baseURL = process.env.BASE_URL || 'http://localhost:3000';
+const authFile = 'tests/e2e/.auth/user.json';
+const useAuth = Boolean(process.env.E2E_USER);
+
+export default defineConfig({
+  testDir: './tests/e2e/specs',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['list'],
+  ],
+  use: {
+    baseURL,
+    screenshot: 'only-on-failure',
+    video: 'on-first-retry',
+    trace: 'on-first-retry',
+  },
+  projects: useAuth
+    ? [
+        { name: 'setup', testMatch: /auth\.setup\.ts/ },
+        {
+          name: 'chromium',
+          use: { ...devices['Desktop Chrome'], storageState: authFile },
+          dependencies: ['setup'],
+        },
+      ]
+    : [{ name: 'chromium', use: devices['Desktop Chrome'] }],
+});

package/custom/harness/playwright/tests/e2e/auth.setup.ts

@@ -0,0 +1,25 @@
+import { test as setup, expect } from '@playwright/test';
+import * as path from 'path';
+
+const authFile = path.join('tests', 'e2e', '.auth', 'user.json');
+
+setup('xác thực', async ({ page }) => {
+  const user = process.env.E2E_USER;
+  const password = process.env.E2E_PASSWORD;
+  const loginPath = process.env.E2E_LOGIN_PATH || '/login';
+  const postLoginPath = process.env.E2E_POST_LOGIN_PATH || '/dashboard';
+
+  if (!user || !password) {
+    throw new Error('E2E_USER và E2E_PASSWORD phải được thiết lập trong .env');
+  }
+
+  await page.goto(loginPath);
+  // Cập nhật các locator bên dưới bằng selector thật từ app (dùng automation-testing skill)
+  await page.getByRole('textbox', { name: 'Email' }).fill(user);
+  await page.getByLabel('Mật khẩu').fill(password);
+  await page.getByRole('button', { name: 'Đăng nhập' }).click();
+
+  const escaped = postLoginPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  await expect(page).toHaveURL(new RegExp(escaped));
+  await page.context().storageState({ path: authFile });
+});

package/custom/harness/playwright/tests/e2e/fixtures/test.ts

@@ -0,0 +1,6 @@
+import { test as base } from '@playwright/test';
+
+export const LOGGED_OUT = { cookies: [], origins: [] } as const;
+
+export const test = base;
+export { expect } from '@playwright/test';

package/custom/harness/playwright/tests/e2e/pages/BasePage.ts

@@ -0,0 +1,9 @@
+import { Page } from '@playwright/test';
+
+export class BasePage {
+  constructor(protected readonly page: Page) {}
+
+  async navigate(path: string): Promise<void> {
+    await this.page.goto(path);
+  }
+}

package/custom/harness/playwright/tests/e2e/support/auth.ts

@@ -0,0 +1,5 @@
+export const AUTH_FILE = 'tests/e2e/.auth/user.json';
+
+export function isAuthEnabled(): boolean {
+  return Boolean(process.env.E2E_USER);
+}

package/custom/mcp-presets/playwright.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--isolated", "--browser", "chromium", "--headless"]
+    }
+  }
+}

package/custom/rules/test-patterns.md

@@ -0,0 +1,70 @@
+# Test Patterns — Quy ước chung cho automation-testing
+
+Tài liệu này được skill `automation-testing` đọc ở Phase 1 và áp dụng khi sinh test.
+Mục tiêu: test ổn định, dễ đọc, ít vỡ khi UI đổi.
+
+## Nguyên tắc chọn locator (ưu tiên từ trên xuống)
+
+1. `getByRole(role, { name })` — bám theo accessibility, bền nhất.
+2. `getByLabel(text)` — cho input có `<label>`.
+3. `getByPlaceholder(text)` — khi không có label.
+4. `getByText(text)` — cho message, nội dung tĩnh.
+5. `getByTestId(id)` — khi dev đã gắn `data-testid`.
+6. CSS / XPath — **chỉ khi bất đắc dĩ**, kèm comment lý do.
+
+> Locator phải lấy từ DOM thật (Phase 3 qua Playwright MCP), không tự bịa tên.
+
+## Quy ước chung
+
+- Mỗi test độc lập: tự `navigate` tới trang cần test, không phụ thuộc test trước.
+- Page Object: 1 file / 1 màn hình; locator khai báo ở constructor; action là method.
+- Spec import `{ test, expect }` từ `tests/e2e/fixtures/test.ts`.
+- ID test (`TC01`, `TC02`...) khớp bảng test case đã chốt ở Phase 2.
+- Tên test, comment viết tiếng Việt.
+- Không hardcode tài khoản/dữ liệu thật; dùng dữ liệu test do tester cung cấp.
+
+---
+
+## Pattern 1 — Login
+
+Steps điển hình: vào trang login → nhập email/password → submit.
+- Thành công: `await expect(page).toHaveURL(/dashboard/)`.
+- Sai thông tin: `await expect(errorMessage).toBeVisible()`.
+- Validation rỗng: submit ngay → `await expect(page.getByText('... bắt buộc')).toBeVisible()`.
+
+## Pattern 2 — Form validation
+
+- Submit khi field rỗng → kiểm tra message bắt buộc của từng field.
+- Nhập sai định dạng (email, số điện thoại) → kiểm tra message định dạng.
+- Nhập hợp lệ → submit thành công (toast / redirect / record mới xuất hiện).
+
+## Pattern 3 — CRUD (Create / Read / Update / Delete)
+
+- **Create**: mở form → điền → submit → khẳng định record xuất hiện trong list.
+- **Read**: tìm/lọc → khẳng định kết quả đúng.
+- **Update**: mở record → sửa → lưu → khẳng định giá trị mới hiển thị.
+- **Delete**: xóa → xác nhận → khẳng định record biến mất.
+- Mẹo: tạo dữ liệu có hậu tố thời gian/ngẫu nhiên để tránh trùng giữa các lần chạy.
+
+## Pattern 4 — Modal / Dialog
+
+- Mở modal → `await expect(dialog).toBeVisible()`.
+- Thao tác trong modal dùng locator scope trong dialog: `dialog.getByRole(...)`.
+- Đóng/confirm → khẳng định modal đóng (`toBeHidden`) và side-effect đúng.
+
+## Pattern 5 — Table / Pagination / Search
+
+- Search: nhập từ khóa → khẳng định hàng khớp xuất hiện, hàng không khớp biến mất.
+- Pagination: sang trang → khẳng định nội dung trang đổi.
+- Dùng `getByRole('row')`, `getByRole('cell')` để bám bảng theo accessibility.
+
+## Pattern 6 — Auth-gated pages (storageState)
+
+Cơ chế có sẵn trong repo — **ưu tiên dùng**, đừng đăng nhập lại trong từng test:
+
+- Đăng nhập **1 lần** ở `tests/e2e/auth.setup.ts`, lưu phiên vào `.auth/user.json`.
+- Bật bằng env `E2E_USER` (+ `E2E_PASSWORD`, `E2E_LOGIN_PATH`, `E2E_POST_LOGIN_PATH`).
+- Khi bật, mọi test chạy ở trạng thái **đã đăng nhập** sẵn — không cần `beforeEach` login.
+- Test cần **chưa đăng nhập** (test login/logout): `test.use({ storageState: LOGGED_OUT })`
+  ở đầu spec (`LOGGED_OUT` import từ `../../fixtures/test`).
+- Selector trong `auth.setup.ts` phải là selector THẬT của trang login (lấy ở Phase 3).