@fui-org/fui-cli 2.1.4 → 2.2.0

package/skills/{fui-skill → fui}/references/verification.md

@@ -30,21 +30,21 @@ Tiers differ ~100× in cost per run:
 | `Unknown custom element: <f-…>` / empty component                                   | **1**                                                                             | wrong name or missing required import                                                                                                                                                            |
 | Chart draws nothing                                                                 | **1** (missing `echarts.min.js`/`fechart.js`, most cases) → **5** (0-size canvas) |                                                                                                                                                                                                  |
 | Misaligned columns, cramped row                                                     | **2** (Σw > 12)                                                                   |                                                                                                                                                                                                  |
-| Dialog won't open                                                                   | **2** (`⚠ không thấy lệnh mở`) → **3**                                            |                                                                                                                                                                                                  |
+| Dialog won't open                                                                   | **2** (`⚠ no opener`) → **3**                                                     |                                                                                                                                                                                                  |
 | Wrong action order · infinite watch loop · CONFIRM/MESS wrong branch                | **3**                                                                             |                                                                                                                                                                                                  |
 | Wrong numbers · `undefined`/`NaN` on page                                           | **3**                                                                             | almost always `OUT`/mapData on the wrong key, not display                                                                                                                                        |
 | API returns unexpected shape                                                        | `fui sp verify` (static, **calls no endpoint**)                                   | infers from the real SP body + generates `--mocks` for tier 3. Only metadata reads: `OBJECT_DEFINITION` when no local `.sql`, `sys.database_permissions` with `--check-grant`; never runs the SP |
 | One `uc-*.vue` wrong                                                                | **4**                                                                             | once proven, remaining bugs are assembly                                                                                                                                                         |
 | Horizontal overflow · wrong height · leaking style · bad spacing · broken on mobile | **5**                                                                             | only tier seeing geometry                                                                                                                                                                        |
-| Import/asset not loaded                                                             | **5**, section `⛔ MÔI TRƯỜNG THIẾU FILE`                                         | environment error — **don't** edit the module for it                                                                                                                                             |
-| Suspected "platform library bug"                                                    | **5**, check `⛔ ASSET CŨ` FIRST                                                  | stale asset ⇒ on-disk copy ran; CDN conclusions worthless                                                                                                                                        |
+| Import/asset not loaded                                                             | **5**, section `⛔ MISSING ENV FILES`                                             | environment error — **don't** edit the module for it                                                                                                                                             |
+| Suspected "platform library bug"                                                    | **5**, check `⛔ STALE, UNVERIFIED ASSETS` FIRST                                  | stale asset ⇒ on-disk copy ran; CDN conclusions worthless                                                                                                                                        |
 | **Permission-gated** button/menu hidden for real users but shown in preview         | **1** after `fui right function list`                                             | undefined code ⇒ `rightTest()` always false, no JS error. Tiers 3/5 **pre-grant** scanned codes so they always show — [permission-system.md](permission-system.md)                               |
 
-**Stale assets:** `--render` revalidates every asset per run (conditional GET; trace shows `N revalidate 304`). `⛔ ASSET CŨ, KHÔNG XÁC MINH ĐƯỢC` = network failed, on-disk copy ran ⇒ "library X has a bug" from that run is **unusable**; reconnect and re-render, or `--refresh-assets`. `ℹ️ ASSET PLATFORM ĐÃ ĐỔI` = platform file changed between runs — behavior changed without a `module.json` edit ⇒ look there first.
+**Stale assets:** `--render` revalidates every asset per run (conditional GET; trace shows `N revalidate 304`). `⛔ STALE, UNVERIFIED ASSETS` = network failed, on-disk copy ran ⇒ "library X has a bug" from that run is **unusable**; reconnect and re-render, or `--refresh-assets`. `ℹ️ PLATFORM ASSETS CHANGED` = platform file changed between runs — behavior changed without a `module.json` edit ⇒ look there first.
 
-**Read the `--render` report top-down:** `═══ CHẨN ĐOÁN ═══` groups failures by **where to fix** — `[MÔI TRƯỜNG]` (fix first; the others may be consequences) · `[MODULE]` (module.json/script.js/component) · `[HIỂN THỊ]` (DOM audit + image). `↪` = cheaper tier that should have caught it.
+**Read the `--render` report top-down:** `═══ DIAGNOSIS ═══` groups failures by **where to fix** — `[ENV]` (fix first; the others may be consequences) · `[MODULE]` (module.json/script.js/component) · `[VIEW]` (DOM audit + image). `↪` = cheaper tier that should have caught it.
 
-**STOP re-rendering** when `Δ so với lượt trước` shows _no metric changed_: the fix missed the bug. Drop to tiers 1–3 to learn why, then return.
+**STOP re-rendering** when `Δ vs previous run` shows _no metric changed_, or the report carries a `🛑 STUCK` block: the fix missed the bug. Drop to tiers 1–3 to learn why, then return.
 
 ---
 
@@ -115,10 +115,10 @@ Tiers differ ~100× in cost per run:
 - [ ] Read each warning — may be intentional (unlisted component, optional param...), never skip unread
 - [ ] **`[design]`** warnings (colored dialog toolbar, red delete button, odd dialog width, no floating label, delete without CONFIRM, redundant Close button, hand-built v-snackbar/v-alert instead of MESS/MESSBOX, main f-table/f-sheet without `":height": -16` so the page scrolls instead of the table...) — **must fix** unless the user explicitly asked otherwise this session
 - [ ] Strict mode (`FUI_STRICT=1`): errors BLOCK publish
-- [ ] `fui module outline`, READ the tree: row Σw ≤12? `⚠ không thấy lệnh mở`? `⚠ không thấy nơi gọi`? `⚠ không thấy dùng`?
+- [ ] `fui module outline`, READ the tree: row Σw ≤12? `⚠ no opener`? `⚠ never called`? `⚠ unused in controls/watch/actions`?
 - [ ] Complex runtime logic (action chain, watch cascade, dialog flow): `fui module simulate` with main-flow `--scenario` + `--mocks` (shape from `fui sp verify` snippet) + asserts — fix every `⚠` and ✘ first. Your `--mocks` always win; a static API with NO mock whose SP is confirmed read-only (`fui sp verify`/local `.sql`) is called for real (max 8 calls/run, cached in `_testdata/`) instead of `{data:[]}` — see the "Live/Cache data" line. SPs with writes are never called
-- [ ] **`--mocks` for existing SPs come from `fui sp verify`, never guessed** — on `🚨 CẤU TRÚC MOCK CHƯA ĐƯỢC KIỂM CHỨNG`, stop, run `fui sp verify`, copy the snippet verbatim (no hand edits). Invented shapes only for SPs not yet deployed
-- [ ] **Final visual QA (Playwright available)**: `fui module simulate --render --vue-data '{..demo data..}' --mocks '{...}'`. READ the screenshot (always inline; big PNG → JPEG) + DOM audit (empty app, overflow, "undefined"/"NaN", broken image, 0-size chart canvas) + JS errors/`[Vue warn]` + final vueData; fix and re-render until clean. **`⛔ MÔI TRƯỜNG THIẾU FILE` first**: environment error — run its suggested command (`fui project sync`/`fui module get`); errors below may be consequences, don't edit module.json for them. How to read screenshots: `ui-screenshot-review.md`. Chart/animation missing → raise `--settle-ms` (e.g. 1500). Open dialog captured as `render-dialog.jpg`. Mobile use → extra run `--device mobile`. No Playwright → skip (command returns install steps)
+- [ ] **`--mocks` for existing SPs come from `fui sp verify`, never guessed** — on `🚨 UNVERIFIED MOCK SHAPE`, stop, run `fui sp verify`, copy its `--mocks snippet` verbatim (no hand edits). Invented shapes only for SPs not yet deployed
+- [ ] **Final visual QA (Playwright available)**: `fui module simulate --render --vue-data '{..demo data..}' --mocks '{...}'`. OPEN and READ the image files the report lists (`Screenshot:`, `Full-page:`; nothing is attached to the output) + DOM audit (empty app, overflow, "undefined"/"NaN", broken image, 0-size chart canvas) + JS errors/`[Vue warn]` + final vueData; fix and re-render until clean. **`⛔ MISSING ENV FILES` first**: environment error — run its suggested command (`fui project sync`/`fui module get`); errors below may be consequences, don't edit module.json for them. How to read screenshots: `ui-screenshot-review.md`. Chart/animation missing → raise `--settle-ms` (e.g. 1500). Open dialog captured as `render-dialog.jpg`. Mobile use → extra run `--device mobile`. No Playwright → skip (command returns install steps)
 - [ ] **Changed project level + module level** (project component/import, `project.json`/menu): publish **project level FIRST**, then render — `--render` loads `$projectData`, project components and project CSS from the server (`_aset`); module-level parts render locally (iterate freely, publish later). **Project components are hard-blocked** (no bypass flag) if a local `uc-*.vue` differs from the server bundle: `fui component preview` → `fui component new`/`update` → render. Blocked because server is newer (web IDE edit) → `fui project sync`, never push over
 
 ### Publish — only what changed
@@ -151,7 +151,7 @@ For `fui module publish html`: preview ran and diff reviewed · user explicitly
 - [ ] Permission check at top: `IF @sys_SystemRight < N BEGIN RAISERROR(N'[Unauthorized]Bạn không có quyền...', 16, 1) RETURN END` — severity always `16`; `[Unauthorized]` prefix required so tAPI returns HTTP 401 ([tapi-reference.md](tapi-reference.md) §5)
 - [ ] No SQL string concatenation (parameterize)
 - [ ] `.sql` has **NO `GRANT EXECUTE`** — tAPI sends one batch, no `GO`, so a GRANT after `END` is **swallowed into the SP body** and runs on every call, silently. `fui sp deploy` grants new procedures and **re-queries `sys.database_permissions` to confirm**
-- [ ] `fui sp deploy` shows `✓ [public] đã có quyền EXECUTE`; on `❗` run exactly the printed GRANT (**don't redeploy**). `fui exec` deploys have no auto-grant (fui warns with the command). Later doubts: `fui sp verify <name> --check-grant`
+- [ ] `fui sp deploy` shows `GRANT EXECUTE ... TO [public]: applied` (new SP) or `[public] has EXECUTE on "<sp>"`; on `grant FAILED` or `[public] lacks EXECUTE` run exactly the printed `fui exec "GRANT ..."` (**don't redeploy**). `fui exec` deploys have no auto-grant (fui warns with the command). Later doubts: `fui sp verify <name> --check-grant`
 
 ### Logic
 
@@ -216,7 +216,7 @@ For `fui module publish html`: preview ran and diff reviewed · user explicitly
 
 1. **Re-read every file changed in that publish first**; don't jump elsewhere
 2. Looks right ⇒ `fui module preview` for server vs local diff
-3. Preview shows `Controls: 0` / `Data keys: 0` ⇒ server holds a broken old version — push again
+3. Preview shows `controls 0, data keys 0` ⇒ server holds a broken old version — push again
 4. Only when local is confirmed correct: check other files (header.html, script.js, imports)
 
 ---

package/skills/{fui-skill → fui}/references/watcher-patterns.md

@@ -1,163 +1,163 @@
-# Watcher Patterns
-
-> Owns: **`watch`: `v_old`, deep-watch, cascading, race control**. Action syntax: [controls-patterns.md](controls-patterns.md).
-
-Use for multi-level dependent forms (Province → District → Ward) and attribute filters (status, type, date, keyword...). Goals: correct FUI structure (`data`, `watch`, `controls`, `set`), no watcher loops, fewer redundant API calls, maintainable large modules.
-
-## 1. Rules
-
-1. **Watch the smallest input key** — an ID or filter field (`provinceID`, `districtID`, `filter.status`), not a large object unless needed.
-2. **Split actions by level** — `handleProvinceChange` only resets dependents and calls `apiLoadDistricts`; `handleDistrictChange` only resets the level below and calls `apiLoadWards`; `applyFilters` holds the final list-loading logic.
-3. **`deep-watch` selectively** — only small filter objects (e.g. `filter`). Never deep-watch large arrays like `items`, `tableData`.
-4. **No self-made loops** — never watch the action's own output var; never watch `items` and write `items` in the callback.
-5. **Guard before API calls** — `IF/THEN/ELSE` to validate input (e.g. no province selected → don't load districts).
-6. **Debounce/race control in `script.js`** — watchers only orchestrate; debounce and stale-response-overwrite protection live in JS helpers.
-7. **Force literal strings only via `IN`** — in an action with `IN`, a string without spaces may be read as an expression → use `` `value`` or `"'value'"`. Full rules: [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental).
-
-## 2. Pattern A: administrative-area cascade
-
-```json
-{
-  "data": [
-    {
-      "formData": {
-        "provinceID": null,
-        "districtID": null,
-        "wardID": null
-      },
-      "provinceList": [],
-      "districtList": [],
-      "wardList": []
-    },
-    {
-      "apiLoadProvinces": {
-        "API": "/api/location/provinces",
-        "OUT": "provinceList"
-      },
-      "apiLoadDistricts": {
-        "API": "/api/location/districts",
-        "IN": { "ProvinceID": "formData.provinceID" },
-        "OUT": "districtList"
-      },
-      "apiLoadWards": {
-        "API": "/api/location/wards",
-        "IN": { "DistrictID": "formData.districtID" },
-        "OUT": "wardList"
-      }
-    },
-    {
-      "handleProvinceChange": [
-        {
-          "districtList": [],
-          "wardList": [],
-          "formData.districtID": null,
-          "formData.wardID": null
-        },
-        {
-          "IF": "formData.provinceID",
-          "THEN": { "CALL": "apiLoadDistricts" }
-        }
-      ],
-      "handleDistrictChange": [
-        {
-          "wardList": [],
-          "formData.wardID": null
-        },
-        {
-          "IF": "formData.districtID",
-          "THEN": { "CALL": "apiLoadWards" }
-        }
-      ]
-    },
-    {
-      "CALL": "apiLoadProvinces"
-    }
-  ],
-  "watch": {
-    "formData.provinceID": { "CALL": "handleProvinceChange" },
-    "formData.districtID": { "CALL": "handleDistrictChange" }
-  }
-}
-```
-
-Key points: watch specific keys; reset lower levels before calling their API; guard against calling with null.
-
-## 3. Pattern B: filter object + deep-watch
-
-```json
-{
-  "data": [
-    {
-      "filter": {
-        "keyword": "",
-        "status": null,
-        "fromDate": null,
-        "toDate": null
-      },
-      "items": []
-    },
-    {
-      "apiLoadItems": {
-        "API": "/api/items/search",
-        "IN": {
-          "Keyword": "filter.keyword",
-          "Status": "filter.status",
-          "FromDate": "filter.fromDate",
-          "ToDate": "filter.toDate"
-        },
-        "OUT": "items"
-      }
-    },
-    {
-      "handleFilterChanged": {
-        "CALL": "apiLoadItems"
-      }
-    }
-  ],
-  "watch": {
-    "deep-watch": {
-      "filter": { "CALL": "handleFilterChanged" }
-    }
-  }
-}
-```
-
-Keep `filter` small and stable. Continuous text-search input → debounce in `script.js`.
-
-## 4. Recommended debounce (script.js)
-
-```javascript
-var filterTimer = null;
-
-function debounceFilter(input) {
-  var callActionName = input && input.callActionName;
-  var waitMs = input && input.waitMs;
-  clearTimeout(filterTimer);
-  filterTimer = setTimeout(function () {
-    CALL(vueData[callActionName]);
-  }, waitMs || 350);
-}
-```
-
-Action in `module.json`:
-
-```json
-{
-  "handleFilterChanged": {
-    "FUN": "debounceFilter",
-    "IN": {
-      "callActionName": "'apiLoadItems'",
-      "waitMs": 350
-    }
-  }
-}
-```
-
-## 5. Watcher QA checklist
-
-1. Watch key small enough (ID/field, not a large object)?
-2. Dependents reset before calling the API?
-3. `IF` guard before API when input is null/empty?
-4. Any watcher loop risk?
-5. Text input needs debounce?
-6. Action with `IN`: literal string rule applied to space-free text values?
+# Watcher Patterns
+
+> Owns: **`watch`: `v_old`, deep-watch, cascading, race control**. Action syntax: [controls-patterns.md](controls-patterns.md).
+
+Use for multi-level dependent forms (Province → District → Ward) and attribute filters (status, type, date, keyword...). Goals: correct FUI structure (`data`, `watch`, `controls`, `set`), no watcher loops, fewer redundant API calls, maintainable large modules.
+
+## 1. Rules
+
+1. **Watch the smallest input key** — an ID or filter field (`provinceID`, `districtID`, `filter.status`), not a large object unless needed.
+2. **Split actions by level** — `handleProvinceChange` only resets dependents and calls `apiLoadDistricts`; `handleDistrictChange` only resets the level below and calls `apiLoadWards`; `applyFilters` holds the final list-loading logic.
+3. **`deep-watch` selectively** — only small filter objects (e.g. `filter`). Never deep-watch large arrays like `items`, `tableData`.
+4. **No self-made loops** — never watch the action's own output var; never watch `items` and write `items` in the callback.
+5. **Guard before API calls** — `IF/THEN/ELSE` to validate input (e.g. no province selected → don't load districts).
+6. **Debounce/race control in `script.js`** — watchers only orchestrate; debounce and stale-response-overwrite protection live in JS helpers.
+7. **Force literal strings only via `IN`** — in an action with `IN`, a string without spaces may be read as an expression → use `` `value`` or `"'value'"`. Full rules: [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental).
+
+## 2. Pattern A: administrative-area cascade
+
+```json
+{
+  "data": [
+    {
+      "formData": {
+        "provinceID": null,
+        "districtID": null,
+        "wardID": null
+      },
+      "provinceList": [],
+      "districtList": [],
+      "wardList": []
+    },
+    {
+      "apiLoadProvinces": {
+        "API": "/api/location/provinces",
+        "OUT": "provinceList"
+      },
+      "apiLoadDistricts": {
+        "API": "/api/location/districts",
+        "IN": { "ProvinceID": "formData.provinceID" },
+        "OUT": "districtList"
+      },
+      "apiLoadWards": {
+        "API": "/api/location/wards",
+        "IN": { "DistrictID": "formData.districtID" },
+        "OUT": "wardList"
+      }
+    },
+    {
+      "handleProvinceChange": [
+        {
+          "districtList": [],
+          "wardList": [],
+          "formData.districtID": null,
+          "formData.wardID": null
+        },
+        {
+          "IF": "formData.provinceID",
+          "THEN": { "CALL": "apiLoadDistricts" }
+        }
+      ],
+      "handleDistrictChange": [
+        {
+          "wardList": [],
+          "formData.wardID": null
+        },
+        {
+          "IF": "formData.districtID",
+          "THEN": { "CALL": "apiLoadWards" }
+        }
+      ]
+    },
+    {
+      "CALL": "apiLoadProvinces"
+    }
+  ],
+  "watch": {
+    "formData.provinceID": { "CALL": "handleProvinceChange" },
+    "formData.districtID": { "CALL": "handleDistrictChange" }
+  }
+}
+```
+
+Key points: watch specific keys; reset lower levels before calling their API; guard against calling with null.
+
+## 3. Pattern B: filter object + deep-watch
+
+```json
+{
+  "data": [
+    {
+      "filter": {
+        "keyword": "",
+        "status": null,
+        "fromDate": null,
+        "toDate": null
+      },
+      "items": []
+    },
+    {
+      "apiLoadItems": {
+        "API": "/api/items/search",
+        "IN": {
+          "Keyword": "filter.keyword",
+          "Status": "filter.status",
+          "FromDate": "filter.fromDate",
+          "ToDate": "filter.toDate"
+        },
+        "OUT": "items"
+      }
+    },
+    {
+      "handleFilterChanged": {
+        "CALL": "apiLoadItems"
+      }
+    }
+  ],
+  "watch": {
+    "deep-watch": {
+      "filter": { "CALL": "handleFilterChanged" }
+    }
+  }
+}
+```
+
+Keep `filter` small and stable. Continuous text-search input → debounce in `script.js`.
+
+## 4. Recommended debounce (script.js)
+
+```javascript
+var filterTimer = null;
+
+function debounceFilter(input) {
+  var callActionName = input && input.callActionName;
+  var waitMs = input && input.waitMs;
+  clearTimeout(filterTimer);
+  filterTimer = setTimeout(function () {
+    CALL(vueData[callActionName]);
+  }, waitMs || 350);
+}
+```
+
+Action in `module.json`:
+
+```json
+{
+  "handleFilterChanged": {
+    "FUN": "debounceFilter",
+    "IN": {
+      "callActionName": "'apiLoadItems'",
+      "waitMs": 350
+    }
+  }
+}
+```
+
+## 5. Watcher QA checklist
+
+1. Watch key small enough (ID/field, not a large object)?
+2. Dependents reset before calling the API?
+3. `IF` guard before API when input is null/empty?
+4. Any watcher loop risk?
+5. Text input needs debounce?
+6. Action with `IN`: literal string rule applied to space-free text values?