@fui-org/fui-cli 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fui-org/fui-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Token-lean CLI for the FUI low-code platform, successor to Fui MCP",
   "keywords": [
     "ai",
@@ -31,9 +31,11 @@
     "lint": "oxlint",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "sync:skill": "bun scripts/sync-skill.ts"
   },
   "devDependencies": {
+    "@fui-org/fui-mcp": "1.4.0",
     "@types/bun": "latest",
     "oxfmt": "^0.70.0",
     "oxlint": "^1.85.0",

package/skills/fui/SKILL.md

@@ -1,109 +1,174 @@
 ---
 name: fui
-description: Use the `fui` CLI to work with FUI (low-code platform) databases — list DB connections, run SQL, read schema, fetch/edit/deploy stored procedures (tAPI spAPI_*). Use instead of the Fui MCP db_* tools whenever the `fui` command is available.
+description: Use the `fui` CLI for FUI (low-code platform) work — projects, modules (get, validate, preview, publish), components, imports, project users, DB connections, SQL, schema, stored procedures (tAPI spAPI_*), workspace files, publish ledger and history. Prefer it over Fui MCP tools whenever `fui` covers the tool (see the map below); same guards, a fraction of the tokens.
 ---
 
 # fui CLI
 
-`fui` is the shell replacement for the Fui MCP `db_*` tools. Run it with your shell tool. It shares the Fui MCP workspace, so connections added in either tool work in both. `fui config` shows which workspace folder is in use and why.
+`fui` is the shell replacement for Fui MCP tools. Run it with your shell tool. It uses the same workspace, connection files, publish ledger, `_history` and error log as Fui MCP, so you can mix the two during the transition.
 
-## Output contract
-
-- stdout carries data only. Query results are TSV with a header row; `NULL` means SQL null; tab, newline and backslash inside cells are escaped as `\t`, `\n`, `\\`.
-- stderr carries `# ...` notes (row counts, truncation) and `error: ...` / `guard: ...` messages.
-- Add `--json` for compact single-line JSON instead of TSV.
-- Exit codes: `0` ok, `1` runtime error (network/SQL), `2` usage error (read the message; it lists valid choices), `3` blocked by a safety guard.
+Domain rules (module.json, controls, tAPI conventions) live in the `fui-skill` skill. Read its `references/` as needed, then run `fui skill loaded`; strict mode (`FUI_MCP_STRICT=1`) blocks deploys until you do.
 
-## Pick a connection
-
-```bash
-fui db list                      # db, engine, default, apiDomain, database, userToken
-```
-
-- `--db <alias>` or `--db <project>/<alias>`. `-p <project>` or env `FUI_PROJECT` also selects the project.
-- With no `--db`: the only connection, else the project default. `sp` commands infer the connection from the object name.
-- Writes (`exec`, write SQL in `query`) never fall back to the default when a project has several connections. Pass `--db`.
-- Engines come from the token. `mssql` goes through tAPI over HTTPS. `postgres`, `mysql` and `sqlite` connect directly with Bun.SQL. `schema` and `sp` commands are MSSQL-only.
+## Output contract
 
-## Read data
+- stdout is data only: TSV with a header when piped, an aligned table in a terminal, `--json` for one-line JSON, `--no-header` to drop the header.
+- stderr carries `# ...` notes and `error:` / `guard:` lines.
+- Exit codes:
+  - `0`: ok, including "skipped: unchanged".
+  - `1`: runtime error (network or SQL).
+  - `2`: usage error. Read the message; it lists the valid choices.
+  - `3`: blocked by a guard, or waiting for `--confirm-write`.
+
+## Targets
+
+- **Project and module**, first match wins:
+  1. `-p <project> -m <module>`. Passing only one of them is an error.
+  2. The current directory, if it is inside `<workspace>/<project>/modules/<module>/`.
+  3. The session target.
+- **Session:** one per `FUI_SESSION` (default `default`). Parallel agents should each set their own `FUI_SESSION`.
+- **Connection:**
+  - `--db <alias>` or `--db <project>/<alias>`.
+  - With no `--db`: the only connection, else one inferred from the object name (`sp` commands), else the default.
+  - Writes never use the default when a project has several connections.
+- `fui file where` prints what resolved and why.
+- `fui config` shows the workspace and API settings with their sources. They inherit from the Fui MCP entry in `~/.claude.json`.
+
+## Fui MCP tool → fui command
+
+Implemented (same guards, same files, same requests as Fui MCP 1.4.0):
+
+| MCP tool                                                        | fui                                                                                                                               |
+| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| session_set / session_read / session_clear / session_resolve    | `use <target>` / `use` / `use --clear` / `resolve <target>`                                                                       |
+| project_list / project_sync                                     | `project list` / `project sync`                                                                                                   |
+| project_new / project_update / project_publish_config           | `project new --data {…}` / `project update --data {id:…}` / `project publish-config`                                              |
+| project_user_search / list / new / update / delete              | `user search <text>` / `user list` / `user add <UserID> --right N` / `user set …` / `user remove <UserID>`                        |
+| module_list / new / update / delete                             | `module list` / `module new <id> --name N` / `module update [--new-id] [--framework] …` / `module delete -p P -m M`               |
+| module_get / module_get_ui / module_get_html                    | `module get [<target>]` / `module get-ui` / `module get-html`                                                                     |
+| module_validate / module_preview                                | `module validate` / `module preview`                                                                                              |
+| module_publish_html / json / script / css                       | `module publish html --approval <token>` / `module publish json` / `… script` / `… css`                                           |
+| component_list / get / new / update / delete                    | `component list` / `component get <name>` / `component new <name>` / `component update <name>` / `component delete <name>`        |
+| file_import_list / get / new / update / upload_content / delete | `import list` / `import get <id>` / `import new …` / `import update <id> …` / `import upload <id> -f file` / `import delete <id>` |
+| db_config_read / db_connect                                     | `db list` / `db add <alias> --token - --api-domain host`                                                                          |
+| db_schema_get / db_schema_read                                  | `schema pull [--prune-local-only]` / `schema [--type T] [--search text]`                                                          |
+| db_sp_list / db_sp_get / db_sp_save                             | `sp list` / `sp get <name> [--print]` / `sp save <name> -f file`                                                                  |
+| db_sp_deploy / db_sp_help                                       | `sp deploy <name>` / `sp help <name\|Fn> [--full]`                                                                                |
+| db_sql_execute / db_sql_execute_nonquery                        | `query "<sql>"` / `exec "<sql>"` (+ `--confirm-write`)                                                                            |
+| skill_get / skill_reference_get / skill_sync                    | `skill get` / `skill ref <path...>` / `skill sync`                                                                                |
+| design_list / design_read                                       | `design list` / `design read <brand>`                                                                                             |
+
+Not in fui yet (use the Fui MCP tool): `right_*`, `db_alias_*`, `db_connect_by_name`, `db_sp_verify`, `db_sp_delete`, `db_sp_rename`, `db_token_rebuild`, `db_user_token_set`, `module_outline`, `module_simulate`, `component_preview`, `error_log_*`.
+
+## Modules
+
+1. `fui module get /project/module` (also a live URL or display name).
+   - It archives local files that differ, deletes `.vue` files the server no longer has, and makes the module the session target.
+2. Edit the files in `<workspace>/<project>/modules/<module>/`. Running `fui` from inside that folder targets it.
+3. `fui module validate`: fix every error; it only reads local files.
+4. Publish:
+   - **Whole module, including header/body:** `fui module preview` → show the changes to the user → after approval `fui module publish html --approval <token>`.
+     - The token breaks if any payload file changes after the preview.
+   - **One file:** `fui module publish json|script|css`, `fui component update <name>`, or `fui file push <path...>`, which routes each path to the right publisher.
+   - Unchanged files are skipped via the publish ledger.
+5. `fui file status` lists what is still unpublished.
+
+`fui remote module --part ui|html|script|css|load|components|imports` and `fui remote project --part config|modules|…` show the server copy without touching the workspace. `fui remote diff <path...>` compares local files with the server.
+
+Ask the user before `module delete`, `component delete`, `import delete` and `user remove`.
+
+## Data
 
 ```bash
 fui query "SELECT TOP 20 * FROM tblStudent WHERE ClassID = 5" --db lhu-docs/docs
-fui query -f report.sql --limit 0      # --limit 0 = no row cap (default 200)
+fui query -f report.sql --limit 0        # default cap 200 rows; 0 = all
 echo "SELECT 1 AS x" | fui query -
 ```
 
-Narrow with `TOP`/`WHERE` before raising `--limit`. Every row costs tokens.
+Narrow with `TOP`/`WHERE` first. Every row you read costs tokens.
 
 ## Structure (MSSQL)
 
 ```bash
-fui schema --filter student            # one compact DDL line per table/view/proc
-fui schema --procs --filter spAPI_     # only procedures/functions
-fui schema pull                        # refresh cache + local .sql bodies from server
-fui sp list --filter Student           # name, kind (API, API File, Procedure, Function, local-only), local
+fui schema --search studentid            # compact DDL lines; --search matches the whole line (columns, params)
+fui schema --type API --search Student   # Table View API "API File" Procedure Function
+fui schema pull                          # refresh schema.json + every local .sql body
+fui sp list --search Student             # columns: db name kind count local
 ```
 
-Prefer `fui schema` over querying `sys.*` yourself. The cache pulls automatically the first time.
+- With no cache, `schema` fails and tells you to run `fui schema pull`. It never pulls on its own.
+- A `# warning: ... last synced N days ago` note means pull before trusting the names.
+- `schema pull` archives and deletes local `.sql` files whose objects were dropped on the server.
+- It only lists drafts that exist in neither schema. `--prune-local-only` archives those too, but only once the user confirms they are stale.
 
-## Change stored procedures (MSSQL)
+## Stored procedures (MSSQL)
 
-1. `fui sp get spAPI_Student_Select` saves the live body to `_db/<alias>/<name>.sql` and prints the path.
-   For a new SP: `fui sp path spAPI_New --db <ref>` prints where to create the file.
-2. Edit that file with your file tools. `CREATE` or `ALTER` both work; deploy fixes the verb.
-3. `fui sp deploy spAPI_Student_Select` does all of this:
-   - archives the live body to `_history/` as the rollback copy
-   - runs the file
-   - grants `EXECUTE` to `[public]` for new procedures and verifies the grant
-   - clears the tAPI parameter cache for `spAPI_*` names
-4. If the output says the grant failed, do **not** redeploy. Run the printed `fui exec "GRANT ..."` line.
+1. `fui sp get <name>` saves the live body to `_db/<alias>/<name>.sql`. A differing local copy is archived first.
+   - For a new SP: `fui sp path <name> --db <ref>`, or `fui sp save <name> -f file.sql --db <ref>`.
+2. Edit the file. `CREATE` versus `ALTER` does not matter.
+3. `fui sp deploy <name>`:
+   - saves the live body as a rollback copy
+   - fixes the verb
+   - grants `EXECUTE` to `[public]` on new procedures and checks it
+   - clears the tAPI cache
+4. If the grant failed, do **not** redeploy. Run the printed `fui exec "GRANT ..."`.
 
-`fui sp help spAPI_X` shows the tAPI parameter list and clears its cache without redeploying.
+## Writes need the user
 
-## Write data (needs the user)
+- Writes to real data exit `3` until you add `--confirm-write`. That covers `INSERT`, `UPDATE`, `DELETE`, `MERGE` and `TRUNCATE` in `query` or `exec`, and `ALTER TABLE ... ALTER COLUMN`.
+- Add `--confirm-write` **only after the user approved that exact write in chat.**
+- Always blocked, with no flag to unlock them. Show the SQL to the user to run by hand:
+  - `DROP TABLE`
+  - `ALTER TABLE ... DROP COLUMN` or `SWITCH`
+  - `DELETE`/`UPDATE` without `WHERE` in `exec`
+- Never write or call a live API SP "to test" it. Read its body.
+
+## Workspace files (local, no network)
 
 ```bash
-fui exec "UPDATE tblX SET Status = 1 WHERE ID = 42" --db lhu-docs/docs --confirm-write
+fui file where                     # workspace, project, module, dirs, and why
+fui file status [--all]            # files changed since the last publish/sync, with the command to push each
+fui file history <path>            # archived versions in _history, newest first
+fui file restore <path> [--at YYYYMMDD_HHMMSS]   # the current file is archived first
+fui file ledger <path...> [--mark|--forget]
 ```
 
-- Any `INSERT`/`UPDATE`/`DELETE`/`MERGE`/`TRUNCATE` or `ALTER COLUMN` exits `3` until `--confirm-write` is added.
-- Add `--confirm-write` **only after the user approved that exact write in chat**. Never add it on your own to get past the guard.
-- These are always blocked, with no flag to unlock them: `DROP TABLE`, `ALTER TABLE ... DROP COLUMN`/`SWITCH`, and `DELETE`/`UPDATE` without `WHERE`. Show the SQL to the user to run by hand.
-- Never run a write or call a live API SP "to test" it. Read the SP body instead.
+## Compose with shell
+
+Filter and loop in the shell. Piped output costs no tokens.
 
-## FUI conventions that matter here
+```bash
+fui sp list --no-header --type API | cut -f2                          # API SP names
+fui sp list --no-header | awk -F'\t' '$5=="yes"{print $2}'            # SPs with a local copy
+fui schema --type Procedure | grep -i tblStudent | cut -d' ' -f3      # procedures mentioning a word
+fui sp list --no-header --search Student | cut -f2 | xargs -n1 fui sp get
+fui query "SELECT TOP 5 ID, Name FROM tblX" --json | jq -r '.[].Name'
+```
 
-- tAPI exposes `spAPI_<Fn>` as `/<alias>/<Fn>`, `spAPI_AUTH_<Fn>` as `/<alias>/auth/<Fn>`, and `spAPIFILE_*` for file endpoints. The alias is the connection name.
-- tAPI SP parameters must not have default values (`@x int = 0`). Deploy blocks them with exit `3`.
-- Signal errors in SPs with `RAISERROR`. Callers read `Message`.
-- Every new procedure needs `GRANT EXECUTE ... TO [public]`. Deploy handles it; raw `fui exec CREATE PROCEDURE` does not.
+- Check exit codes. An exit `3` inside a loop means ask the user; do not retry.
+- Never put `--confirm-write` in a loop or `xargs`.
 
-## Connections and tokens
+## Connections and secrets
 
 ```bash
-printf %s "$TOKEN" | fui db add docs -p lhu-docs --token - --api-domain tapi.lhu.edu.vn
-fui db add local -p demo --conn-env PG_URL          # postgres://user:pass@host/db
-fui db add cache -p demo --conn-env SQLITE_URL      # sqlite:///abs/path/app.db
+printf %s "$TOKEN" | fui db add docs -p lhu-docs --token - --api-domain tapi.lhu.edu.vn --user-token-env UT
+fui db add local -p demo --conn-env PG_URL        # postgres:// mysql:// sqlite:// connect directly
 fui db default lhu-docs/docs
 fui db test --db lhu-docs/docs
-fui token decode --db lhu-docs/docs                 # engine, server, database, user (no password)
-fui token encode --server S --database D --uid U --pwd-env PWD   # Base64 MSSQL dbToken
+fui token decode --db lhu-docs/docs               # never shows the password
 ```
 
-- A dbToken is Base64 of a connection string.
-- Secrets are accepted only from stdin (`-`) or `--*-env VAR`. Never echo, log or paste token values.
-- `db add` tests with `SELECT 1` before saving (`--no-test` skips the test). The previous `_connections.json` is archived to `_history/`.
+Secrets are accepted only from stdin (`-`) or `--*-env VAR`. Never echo or paste token values.
 
-## Workspace location
+- Never `cat`, `jq` or otherwise print `_db/_connections.json`, `_db/config.json` or MCP config files. Use `fui db list`, `fui token decode` or `fui config`; they never print secrets.
+- `fui db list` shows a pre-1.4 `_db/config.json` as `engine=legacy`. Migrate it with `fui db import-legacy -p <project>`.
 
-The workspace is picked in this order: `--workdir` flag, then `FUI_MCP_WORKDIR` env, then `fui config set workdir`, then the Fui MCP workdir in `~/.claude.json`, then `~/.fui-mcp/workspaces`.
-
-```bash
-fui config                              # effective workdir and its source
-fui config set workdir ~/work/fui       # persist a custom location
-fui config unset workdir
-```
+## FUI conventions
 
-## Help
+- tAPI routes:
+  - `spAPI_<Fn>` → `/<alias>/<Fn>`
+  - `spAPI_AUTH_<Fn>` → `/<alias>/auth/<Fn>`
+  - `spAPIFILE_*` → file endpoints
+- tAPI parameters must not have default values (`@x int = 0`). Deploy blocks them.
+- Every new procedure needs `GRANT EXECUTE ... TO [public]`. `sp deploy` does it; raw `exec` only reports it.
 
 `fui --help` lists commands. `fui <command> --help` shows usage for one command.

package/skills/fui-skill/README.md

@@ -0,0 +1,112 @@
+# FUI Skill
+
+> Agent Skill hỗ trợ AI phát triển web module theo kiến trúc metadata-driven của FUI — nơi giao diện và logic được định nghĩa hoàn toàn bằng JSON.
+
+## ✨ Tổng quan
+
+**FUI Skill** cung cấp cho AI agent các hướng dẫn và công cụ để xây dựng FUI web module, bao gồm:
+
+- 📐 **Kiến trúc metadata-driven** — Giao diện và logic định nghĩa trong `module.json`
+- 🧱 **Hệ thống grid bắt buộc** — Cấu trúc container > rows > cols nhất quán
+- ⚡ **Action Protocol** — Gọi API, điều kiện, callback theo cách khai báo
+- 🧩 **Template có sẵn** — Form, CRUD table, dialog, Vue component
+- 🔍 **Đảm bảo chất lượng** — Review code và phân tích edge-case tích hợp
+- 🛠️ **Công cụ module** — Lưu và publish module/component qua script
+
+## 📦 Cài đặt
+
+```bash
+npx skills add fui-labs/fui-skill
+```
+
+## 📁 Cấu trúc thư mục
+
+```
+fui-skill/
+├── SKILL.md              # VĂN BẢN CHÍNH SÁCH: Session Start Protocol, quy tắc cứng,
+│                         #   cổng quyết định, chuỗi publish. KHÔNG dạy cách làm.
+├── metadata.json         # Manifest (documentation-only)
+├── examples/             # Template mẫu (module/f-table/project-patterns.json + component.vue)
+├── references/           # 44 file tài liệu chi tiết (load theo nhu cầu)
+│   ├── INDEX.md              # ROUTER: tình huống/component → file cần load (Tier A)
+│   ├── controls-patterns.md  # Value resolution, action engine, layout grid, control object (Tier A)
+│   ├── module-structure.md   # Cấu trúc file module/project (Tier A)
+│   ├── design-modes.md       # App-mode vs Web-mode, {projectId}/DESIGN.md, giới hạn border-radius
+│   ├── controls-styling-vocabulary.md  # Bộ class/prop/style được duyệt
+│   ├── script-map.md         # Bản đồ script + thư viện đã bundled (đừng thêm CDN trùng)
+│   ├── ui-patterns.md        # UI core (+ ui-table-cell / ui-dialog / ui-crosswindow / ui-layout)
+│   ├── components-echart.md  # f-echart (+ echart-templates.md)
+│   ├── tapi-reference.md     # tAPI core (+ tapi-permission-patterns / tapi-file-api)
+│   ├── permission-system.md  # Phân quyền: SystemRight vs FunctionRight, 4 tool quản lý định nghĩa quyền
+│   ├── db-workflow.md        # Kết nối DB/SP (+ db-table-design.md)
+│   ├── system-design.md      # Thiết kế app nhiều module
+│   └── ...                   # component-*, verification, tools-registry, ...
+└── scripts/              # Mã nguồn runtime (component.js, componentTable.js, defaultfunction.js, fastproject.js)
+```
+
+> Bản đồ đầy đủ tình huống → file: xem [references/INDEX.md](references/INDEX.md).
+
+**Nguyên tắc biên tập — canonical owner:** mỗi sự thật chỉ được viết đầy đủ ở **đúng một file**; nơi
+khác chỉ để link. Mỗi reference mở đầu bằng một dòng `> File này sở hữu: X. Về Y xem <file>.md.` —
+đọc dòng đó để biết nội dung mới thuộc về đâu, đừng viết lại vào `SKILL.md`.
+
+## 🚀 Bắt đầu nhanh
+
+Sau khi cài đặt, agent sẽ tự động sử dụng skill này khi bạn yêu cầu **tạo, chỉnh sửa hoặc review FUI module**.
+
+### Tạo module mới
+
+> *"Tạo module `user-management` có bảng dữ liệu và dialog thêm/sửa."*
+
+Agent sẽ:
+1. Tạo thư mục module với `module.json`, `_info.json`, `script.js`
+2. Áp dụng hệ thống grid layout bắt buộc
+3. Sử dụng Action Protocol để tích hợp API
+4. Tuân theo coding standards và best practices
+
+### Các khái niệm chính
+
+| Khái niệm | Mô tả |
+|:---|:---|
+| **module.json** | File chính định nghĩa `data`, `watch`, `controls`, và `set` |
+| **Action Protocol** | Khai báo action bằng `API`, `IN`, `OUT`, `CALL`, `IF/THEN/ELSE` |
+| **Grid System** | Cấu trúc bắt buộc `container > rows > cols` cho mọi layout |
+| **Control Object** | Phần tử UI được định nghĩa bởi `el`, `attr`, `w`, `col`, `innerHTML` |
+
+### Ví dụ — Lấy dữ liệu bằng Action
+
+```json
+{
+  "fetchUsers": {
+    "API": "/api/users",
+    "IN": { "GroupID": "vueData.selectedGroup" },
+    "OUT": "userList",
+    "CALLBACK": { "MESS": "Tải thành công!" }
+  }
+}
+```
+
+## 📚 Tài liệu tham khảo
+
+| Tài liệu | Mô tả |
+|:---|:---|
+| [INDEX.md](references/INDEX.md) | **Router** — tình huống/component → file cần load |
+| [controls-patterns.md](references/controls-patterns.md) | Action engine, value resolution, layout grid |
+| [module-structure.md](references/module-structure.md) | Cấu trúc file module/project |
+| [ui-patterns.md](references/ui-patterns.md) | UI core (data/watch/toolbar) + các file ui-* tách theo tình huống |
+| [tapi-reference.md](references/tapi-reference.md) | tAPI SP naming, params, response + permission/file-api |
+| [permission-system.md](references/permission-system.md) | Phân quyền: SystemRight (cấp bậc) vs FunctionRight (theo chức năng), 4 tool quản lý định nghĩa quyền |
+| [system-design.md](references/system-design.md) | Thiết kế app nhiều module từ mô tả |
+| [verification.md](references/verification.md) | Review code & checklist definition-of-done |
+
+## 🤝 Đóng góp
+
+Skill này là **tài liệu sống**, liên tục được cập nhật. Sau khi hoàn thành các task phức tạp, agent sẽ hỏi:
+
+> *"Có bài học, pattern hoặc chỉnh sửa nào từ task này cần bổ sung vào FUI skill không?"*
+
+Phản hồi sẽ được tích hợp bằng cách cập nhật hướng dẫn, thêm tài liệu mới, hoặc loại bỏ thông tin lỗi thời — đảm bảo skill luôn phản ánh best practices mới nhất.
+
+## 📄 Giấy phép
+
+MIT