@relipa/ai-flow-kit 0.1.5 → 0.1.7-beta.0

package/docs/common/workflows/figma.md

@@ -1,105 +1,176 @@
-# Figma → Component Workflow
-
-Generate UI components directly from Figma designs using the `figma-to-component` skill.
-
----
-
-## Prerequisites
-
-Choose one adapter based on your setup:
-
-### Option A — REST API (recommended, no Desktop required)
-
-```bash
-ak init -a figma
-# Prompts for FIGMA_API_TOKEN
-```
-
-Get your token: [figma.com/settings](https://www.figma.com/settings) → Security → Personal access tokens → Create new token (File content: read).
-
-### Option B — Official Figma MCP (requires Figma Desktop app)
-
-```bash
-ak init -a figma-desktop
-# No token needed — uses Desktop app session
-```
-
-Requirements: Figma Desktop app installed and the target file open before invoking the skill.
-
----
-
-## Getting a Figma Node URL
-
-1. Open your file in Figma (browser or Desktop)
-2. Right-click on a frame or component → **Copy link to selection**
-3. The URL looks like:
-   ```
-   https://www.figma.com/design/FILEKEY/FileName?node-id=123-456
-   ```
-   - `FILEKEY` — the file identifier (between `/design/` and the next `/`)
-   - `node-id=123-456` — the specific frame or component to generate
-
-You can also link to the entire file (no `node-id`) to let the skill list available frames.
-
----
-
-## Trigger the Skill
-
-Paste the Figma URL into Claude Code with a generation request:
-
-```
-Generate component from this Figma frame:
-https://www.figma.com/design/XXXXX/App?node-id=123-456
-```
-
-```
-Implement the UserCard UI from Figma:
-https://www.figma.com/design/XXXXX/App?node-id=78-910
-```
-
-```
-Read Figma and generate component following my project conventions:
-https://www.figma.com/design/XXXXX/App?node-id=42-0
-```
-
----
-
-## What to Expect
-
-The skill outputs in this order:
-
-1. **Design Summary** — layout structure, color palette, typography scale used in the design
-2. **Component file** — complete code for your detected framework (React, Next.js App Router, Vue 3, or Angular)
-3. **Usage example** — how to import and use the component
-4. **Notes** — anything that couldn't be mapped 1:1 from Figma (custom fonts, unsupported effects, etc.)
-
-**Framework auto-detection order:**
-1. Read `CLAUDE.md` for framework identifier (`nextjs-app-router`, `reactjs`, `vue-nuxt`, `angular`)
-2. Scan project files (`app/` dir → App Router, `angular.json` → Angular, `nuxt.config.*` → Vue)
-3. Fallback → Next.js / React
-
----
-
-## Review Checklist
-
-After the component is generated, verify:
-
-- [ ] Layout matches Figma (flex direction, alignment, gap)
-- [ ] Colors are correct (Tailwind class or arbitrary value)
-- [ ] Typography matches (size, weight, line-height)
-- [ ] Spacing correct (padding, margin, gap)
-- [ ] Interactive states handled (`'use client'` in App Router, variants in React/Vue/Angular)
-- [ ] Images use correct component (`next/image` for Next.js, `<img>` for others)
-- [ ] `className` / `class` prop exposed for external overrides
-
----
-
-## Troubleshooting
-
-| Problem | Fix |
-|---|---|
-| `get_figma_data` tool not found | Run `ak init -a figma` to configure the MCP |
-| "Invalid API token" | Token expired — create a new one at figma.com/settings |
-| Wrong node generated | Check the `node-id` in the URL matches your selection in Figma |
-| Figma Desktop MCP not responding | Ensure Figma Desktop app is open with the file loaded |
-| Component uses wrong framework | Add framework to `CLAUDE.md` (e.g. `nextjs-app-router`) |
+# Figma → Component Workflow
+
+Generate UI components directly from Figma designs using the `figma-to-component` skill.
+
+---
+
+## Prerequisites
+
+Choose one adapter based on your setup:
+
+> **Which adapter?** The REST API is rate-limited **per seat** (see [Rate limits](#rate-limits-429)
+> below): a View/Collab seat gets only ~6 heavy calls per MONTH — effectively unusable.
+> - Token from a **Dev/Full seat** → Option A (REST) works fine with the batched strategy.
+> - Only a View/Collab seat, or design-heavy work (many frames, art-heavy exports) →
+>   prefer **Option B (Figma Desktop)** — it uses the local app session and consumes no REST quota.
+
+### Option A — REST API (no Desktop required; needs a Dev/Full-seat token)
+
+```bash
+ak init -a figma
+# Prompts for FIGMA_API_TOKEN
+```
+
+Get your token: [figma.com/settings](https://www.figma.com/settings) → Security → Personal access tokens → Create new token (File content: read). Create it from an account with a **Dev or Full seat** — a View/Collab seat's token is capped at ~6 Tier 1 calls/month.
+
+### Option B — Official Figma MCP (requires Figma Desktop app)
+
+```bash
+ak init -a figma-desktop
+# No token needed — uses Desktop app session
+```
+
+Requirements: Figma Desktop app installed and the target file open before invoking the skill.
+
+---
+
+## Getting a Figma Node URL
+
+1. Open your file in Figma (browser or Desktop)
+2. Right-click on a frame or component → **Copy link to selection**
+3. The URL looks like:
+   ```
+   https://www.figma.com/design/FILEKEY/FileName?node-id=123-456
+   ```
+   - `FILEKEY` — the file identifier (between `/design/` and the next `/`)
+   - `node-id=123-456` — the specific frame or component to generate
+
+You can also link to the entire file (no `node-id`) to let the skill list available frames.
+
+---
+
+## Trigger the Skill
+
+Paste the Figma URL into Claude Code with a generation request:
+
+```
+Generate component from this Figma frame:
+https://www.figma.com/design/XXXXX/App?node-id=123-456
+```
+
+```
+Implement the UserCard UI from Figma:
+https://www.figma.com/design/XXXXX/App?node-id=78-910
+```
+
+```
+Read Figma and generate component following my project conventions:
+https://www.figma.com/design/XXXXX/App?node-id=42-0
+```
+
+---
+
+## What to Expect
+
+The skill outputs in this order:
+
+1. **Design Summary** — layout structure, color palette, typography scale used in the design
+2. **Component file** — complete code for your detected framework (React, Next.js App Router, Vue 3, or Angular)
+3. **Usage example** — how to import and use the component
+4. **Notes** — anything that couldn't be mapped 1:1 from Figma (custom fonts, unsupported effects, etc.)
+
+**Framework auto-detection order:**
+1. Read `CLAUDE.md` for framework identifier (`nextjs-app-router`, `reactjs`, `vue-nuxt`, `angular`)
+2. Scan project files (`app/` dir → App Router, `angular.json` → Angular, `nuxt.config.*` → Vue)
+3. Fallback → Next.js / React
+
+---
+
+## Figma trong Gate workflow
+
+Khi làm việc theo quy trình 5 Gate (xem `CLAUDE.md`) với ticket liên quan UI, Figma được
+nối tự động — không cần gọi skill thủ công:
+
+| Gate | Vai trò Figma |
+|------|----------------|
+| **1** | `read-study-requirement` dò Figma URL trong ticket (hoặc hỏi DEV một lần), đọc design **một lần** qua MCP, lưu artifact `plan/[ticket-id]/design/` (design-context.md + images/ + nodes.json). |
+| **2** | `generate-spec` đọc `design-context.md` → đưa component tree, design tokens, danh sách ảnh vào plan TDD. |
+| **3** | `figma-to-component` chạy ở **Gate mode**: dùng lại cache `nodes.json`, copy ảnh sang `public/assets/figma/`, sinh component (không gọi lại MCP). |
+| **4** | `review-plan` đối chiếu UI đã code với `design-context.md`. |
+
+**Artifact dùng chung** — nguồn sự thật cho mọi Gate sau Gate 1:
+
+```
+plan/[ticket-id]/design/
+├── design-context.md   # layout, tokens, component list, image map
+├── images/             # ảnh export từ Figma
+└── nodes.json          # raw get_figma_data (cache)
+```
+
+**Refresh khi design đổi:** gõ "reload figma" → Gate 1 fetch lại, ghi đè `design/`, cập nhật `Fetched`.
+
+**Ticket không liên quan UI** hoặc không có Figma URL → toàn bộ nhánh Figma được bỏ qua.
+
+---
+
+## Review Checklist
+
+After the component is generated, verify:
+
+- [ ] Layout matches Figma (flex direction, alignment, gap)
+- [ ] Colors are correct (Tailwind class or arbitrary value)
+- [ ] Typography matches (size, weight, line-height)
+- [ ] Spacing correct (padding, margin, gap)
+- [ ] Interactive states handled (`'use client'` in App Router, variants in React/Vue/Angular)
+- [ ] Images use correct component (`next/image` for Next.js, `<img>` for others)
+- [ ] `className` / `class` prop exposed for external overrides
+
+---
+
+## Rate limits (429)
+
+Figma rate-limits the REST API by **endpoint tier × plan × seat** (since 2025-11-17).
+`get_figma_data` (file/nodes) and image renders share the same **Tier 1** bucket:
+
+| Seat of the token owner | Tier 1 budget (file / nodes / render images) |
+|---|---|
+| View / Collab | **~6 calls / MONTH** (any plan) |
+| Dev / Full — Starter | 10 / min |
+| Dev / Full — Professional | 15 / min |
+| Dev / Full — Organization+ | 20 / min |
+
+The fills-map endpoint (`/v1/files/:key/images`) is Tier 2 (25-100/min) — the skill prefers it.
+Downloading image bytes from the returned S3 URLs costs nothing.
+
+> **Measured on a free personal (Starter) account, 2026-07:** the API returned
+> `x-figma-rate-limit-type: low` with `retry-after ≈ 4 days` after only ~4 Tier 1 calls —
+> i.e. free accounts behave like the View/Collab monthly bucket, NOT 10/min. On a free
+> account, budget ONE batched fetch per design and cache everything; for anything heavier
+> use `figma-desktop` or a paid Dev/Full seat.
+
+**Client-side guard:** `ak init` installs a PreToolUse hook
+(`.claude/hooks/figma-rate-limit.js`) that throttles every `mcp__figma__*` call to
+6 REST-call units per 60s (safe under the 10/min Starter budget; `download_figma_images`
+counts as 3 units — it makes up to 3 REST calls internally). It sleeps instead of
+failing, so calls are delayed — never dropped. Tune with `FIGMA_RATE_LIMIT_UNITS`
+(e.g. `15` on a Professional plan).
+
+**When you hit a 429, read the `Retry-After` header:**
+
+- **≤ 60s** → per-minute bucket. Wait and retry once — this is normal on art-heavy frames.
+- **Hours/days, or `X-Figma-Rate-Limit-Type: low`** → per-seat quota. A new token on the same
+  account will NOT help. Fix: use a token from a Dev/Full seat, or switch to
+  `ak init -a figma-desktop`.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `get_figma_data` tool not found | Run `ak init -a figma` to configure the MCP |
+| "Invalid API token" | Token expired — create a new one at figma.com/settings |
+| `429` immediately / every session | Token from a View/Collab seat (~6 calls/month) — see [Rate limits](#rate-limits-429) |
+| Wrong node generated | Check the `node-id` in the URL matches your selection in Figma |
+| Figma Desktop MCP not responding | Ensure Figma Desktop app is open with the file loaded |
+| Component uses wrong framework | Add framework to `CLAUDE.md` (e.g. `nextjs-app-router`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.1.5",
+  "version": "0.1.7-beta.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {
@@ -65,4 +65,4 @@
       "<rootDir>/tests/**/*.test.js"
     ]
   }
-}
+}

package/scripts/create-score-excel.js

@@ -24,6 +24,25 @@ function norm(cmd) {
   return ALIAS_MAP[c] || c;
 }
 
+// ── Version helpers ─────────────────────────────────────────────────────────
+const CURRENT_VERSION = '0.1.5';
+
+function parseVersion(v) {
+  if (!v || v === '-' || v === '' || v.toLowerCase() === 'unknown') return null;
+  const core = v.split('-')[0]; // strip prerelease suffix, e.g. 0.1.5-beta.1 -> 0.1.5
+  const parts = core.split('.').map(n => parseInt(n, 10));
+  if (parts.some(n => Number.isNaN(n))) return null;
+  return parts;
+}
+
+function compareVersion(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const diff = (a[i] || 0) - (b[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
 // ── Parse log file ─────────────────────────────────────────────────────────
 function parseLog(filePath) {
   const lines = fs.readFileSync(filePath, 'utf-8').split(/\r?\n/);
@@ -39,17 +58,19 @@ function parseLog(filePath) {
     if (!user || user === '-' || user === '') continue;
 
     const timestamp = cols[0] || '';
+    const version = cols[5] || '';
     const command = cols[6] || '';
     const ticket = cols[9] || '';
 
     const date = timestamp.split(' ')[0]; // dd/MM/yyyy
 
     if (!users[user]) {
-      users[user] = { email: user, days: new Set(), events: 0, rawCmds: new Set(), gateCmds: [] };
+      users[user] = { email: user, days: new Set(), events: 0, rawCmds: new Set(), gateCmds: [], versions: new Set() };
     }
     const u = users[user];
     u.events++;
     if (date) u.days.add(date);
+    if (version.trim()) u.versions.add(version.trim());
 
     const cmd = norm(command);
     if (cmd) u.rawCmds.add(cmd);
@@ -130,6 +151,19 @@ const SCORE_LABELS = [
   'Sử dụng thường xuyên workflow',
 ];
 
+// ── Version status for a user ──────────────────────────────────────────────
+function getVersionStatus(u) {
+  const all = [...u.versions];
+  const parsed = all.map(v => ({ raw: v, parts: parseVersion(v) })).filter(v => v.parts);
+  if (parsed.length === 0) {
+    return { status: all.length ? 'unknown' : 'none', latest: null, all };
+  }
+  parsed.sort((a, b) => compareVersion(a.parts, b.parts));
+  const latest = parsed[parsed.length - 1];
+  const isOutdated = compareVersion(latest.parts, parseVersion(CURRENT_VERSION)) < 0;
+  return { status: isOutdated ? 'outdated' : 'ok', latest: latest.raw, all };
+}
+
 // ── Build summary row for each user ───────────────────────────────────────
 function buildRow(email, u) {
   const { events, days, rawCmds, gateCmds } = u;
@@ -198,12 +232,12 @@ function buildRow(email, u) {
     impactLabel: '',
     totalScore: score,
     notes,
+    versionStatus: getVersionStatus(u),
   };
 }
 
 // ── Excel writer ───────────────────────────────────────────────────────────
-async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
-  const workbook = new ExcelJS.Workbook();
+function writeExcel(rows, workbook, sheetLabel, fromLabel, toLabel) {
   const sheet = workbook.addWorksheet(`Score ${sheetLabel}`);
 
   sheet.columns = [
@@ -247,20 +281,23 @@ async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
   const hRow = sheet.addRow(HEADERS);
   hRow.height = 36;
   hRow.eachCell(cell => {
-    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF4472C4' } };
+    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF4F81BD' } };
     cell.font = { bold: true, color: { argb: 'FFFFFFFF' }, size: 11 };
     cell.alignment = { vertical: 'middle', horizontal: 'center', wrapText: true };
     cell.border = border;
   });
 
-  // Score → row color
+  // Score → row color (matches requirements/GetPoints-format.png)
   const COLORS = {
-    0: 'FFFFC7CE',
-    1: 'FFFFEB9C',
-    2: 'FFFFFFCC',
-    3: 'FFD9EAD3',
-    4: 'FF93C47D',
-    5: 'FF6AA84F',
+    0: 'FFFFFFFF',
+    1: 'FFF5F8EE',
+    2: 'FFEBF1DE',
+    3: 'FFD8E4BC',
+    4: 'FFC4D79B',
+    5: 'FF76933C',
+  };
+  const FONT_COLORS = {
+    0: 'FFFF0000',
   };
 
   rows.forEach((row, idx) => {
@@ -274,9 +311,11 @@ async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
     r.height = 20;
 
     const fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: COLORS[row.depthScore] || 'FFFFFFFF' } };
+    const fontColor = FONT_COLORS[row.depthScore] || 'FF000000';
     r.eachCell({ includeEmpty: true }, (cell, col) => {
       cell.border = border;
       cell.fill = fill;
+      cell.font = { color: { argb: fontColor } };
       cell.alignment = (col <= 4 || (col >= 9 && col <= 13))
         ? { vertical: 'middle', horizontal: 'center' }
         : { vertical: 'middle', horizontal: 'left', wrapText: false };
@@ -289,8 +328,81 @@ async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
   sheet.views = [{ state: 'frozen', ySplit: 2 }];
   sheet.autoFilter = { from: 'A2', to: 'N2' };
 
+  return sheet;
+}
+
+// ── Version warning sheet ───────────────────────────────────────────────────
+function writeVersionSheet(workbook, rows) {
+  const sheet = workbook.addWorksheet('Version Warning');
+  sheet.columns = [
+    { key: 'no', width: 5 },
+    { key: 'email', width: 30 },
+    { key: 'status', width: 16 },
+    { key: 'latest', width: 16 },
+    { key: 'allVersions', width: 30 },
+    { key: 'note', width: 50 },
+  ];
+
+  const border = {
+    top: { style: 'thin' }, left: { style: 'thin' },
+    bottom: { style: 'thin' }, right: { style: 'thin' },
+  };
+
+  sheet.addRow([`Cảnh báo phiên bản — Yêu cầu phiên bản hiện tại: ${CURRENT_VERSION}`]);
+  sheet.mergeCells('A1:F1');
+  const title = sheet.getCell('A1');
+  title.font = { bold: true, size: 13, color: { argb: 'FF1F3864' } };
+  title.alignment = { vertical: 'middle', horizontal: 'center' };
+  title.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD6DCE4' } };
+  sheet.getRow(1).height = 28;
+
+  const HEADERS = ['#', 'Email', 'Trạng thái', 'Phiên bản mới nhất', 'Các phiên bản dùng trong tuần', 'Ghi chú'];
+  const hRow = sheet.addRow(HEADERS);
+  hRow.height = 20;
+  hRow.eachCell(cell => {
+    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF4F81BD' } };
+    cell.font = { bold: true, color: { argb: 'FFFFFFFF' }, size: 11 };
+    cell.alignment = { vertical: 'middle', horizontal: 'center', wrapText: true };
+    cell.border = border;
+  });
+
+  const warnings = rows.filter(row => row.versionStatus.status === 'outdated' || row.versionStatus.status === 'unknown');
+
+  const STATUS_LABEL = { outdated: 'CŨ HƠN', unknown: 'KHÔNG XÁC ĐỊNH', ok: 'OK', none: 'Không có dữ liệu' };
+  const STATUS_COLOR = { outdated: 'FFFFC7CE', unknown: 'FFFFEB9C' };
+
+  warnings.forEach((row, idx) => {
+    const vs = row.versionStatus;
+    const note = vs.status === 'outdated'
+      ? `Đang dùng ${vs.latest}, chưa cập nhật lên ${CURRENT_VERSION}`
+      : 'Không đọc được phiên bản (giá trị "-" hoặc "unknown") — cần kiểm tra lại';
+    const r = sheet.addRow([
+      idx + 1, row.email, STATUS_LABEL[vs.status], vs.latest || '-', vs.all.join(', ') || '-', note,
+    ]);
+    r.height = 20;
+    const fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: STATUS_COLOR[vs.status] || 'FFFFFFFF' } };
+    r.eachCell({ includeEmpty: true }, (cell, col) => {
+      cell.border = border;
+      cell.fill = fill;
+      cell.alignment = (col <= 4)
+        ? { vertical: 'middle', horizontal: 'center' }
+        : { vertical: 'middle', horizontal: 'left', wrapText: false };
+    });
+  });
+
+  sheet.views = [{ state: 'frozen', ySplit: 2 }];
+  sheet.autoFilter = { from: 'A2', to: 'F2' };
+
+  return warnings;
+}
+
+async function writeExcelFile(rows, outputPath, sheetLabel, fromLabel, toLabel) {
+  const workbook = new ExcelJS.Workbook();
+  writeExcel(rows, workbook, sheetLabel, fromLabel, toLabel);
+  const warnings = writeVersionSheet(workbook, rows);
   await workbook.xlsx.writeFile(outputPath);
-  console.log(`Written: ${outputPath} (${rows.length} users)`);
+  console.log(`Written: ${outputPath} (${rows.length} users, ${warnings.length} version warning(s))`);
+  return warnings;
 }
 
 // ── Canonical user list (fixed order) ─────────────────────────────────────
@@ -315,6 +427,10 @@ const CANONICAL_USERS = [
   'anhnt@relipasoft.com',
   'khanhdd@relipasoft.com',
   'hieunv@relipasoft.com',
+  'cucdt@relipasoft.com',
+  'khanhnv@relipasoft.com',
+  'namhh@relipasoft.com',
+  'tannt@relipasoft.com',
 ];
 
 // Log email → canonical email (for slight mismatches)
@@ -323,7 +439,7 @@ const LOG_EMAIL_ALIAS = {
 };
 
 const EMPTY_USER = (email) => ({
-  email, events: 0, days: new Set(), rawCmds: new Set(), gateCmds: [],
+  email, events: 0, days: new Set(), rawCmds: new Set(), gateCmds: [], versions: new Set(),
 });
 
 // ── Main ───────────────────────────────────────────────────────────────────
@@ -357,6 +473,7 @@ const EMPTY_USER = (email) => ({
       u.events += data.events;
       data.days.forEach(d => u.days.add(d));
       data.rawCmds.forEach(c => u.rawCmds.add(c));
+      data.versions.forEach(v => u.versions.add(v));
       u.gateCmds.push(...data.gateCmds);
     }
   }
@@ -367,5 +484,9 @@ const EMPTY_USER = (email) => ({
     return buildRow(email, u);
   });
 
-  await writeExcel(rows, outputFile, sheetLabel, fromLabel, toLabel);
+  const warnings = await writeExcelFile(rows, outputFile, sheetLabel, fromLabel, toLabel);
+  if (warnings.length) {
+    console.log(`\n⚠️  Version warnings (< ${CURRENT_VERSION} or unknown):`);
+    warnings.forEach(w => console.log(`  - ${w.email}: ${w.versionStatus.latest || 'unknown'} (${w.versionStatus.status})`));
+  }
 })();

package/scripts/detect.js

@@ -74,6 +74,17 @@ class TaskDetector {
                 antiKeywords: [],
                 icon: '🧪',
                 description: 'Writing tests and QA'
+            },
+            'gen-doc': {
+                keywords: [
+                    'gen-doc', 'generate doc', 'generate document', 'tạo tài liệu',
+                    'tài liệu flow', 'tài liệu logic', 'tài liệu điều tra',
+                    'flow document', 'logic document', 'analysis document',
+                    'source analysis', 'feature document', 'system document'
+                ],
+                antiKeywords: ['code', 'fix', 'bug'],
+                icon: '📝',
+                description: 'Generate document from source code / feature analysis'
             }
         };
     }