@fui-org/fui-cli 2.1.4 → 2.2.1

package/skills/fui/references/tools-registry.md

@@ -0,0 +1,214 @@
+# fui commands — safety registry
+
+> Owns: **risk class of every command, "which command for which file" publish rules, what users say → command, DB guards enforced in code, the error-log loop**. DB/SP procedure: [db-workflow.md](db-workflow.md); definition of done: [verification.md](verification.md). Flags: `fui <command> --help` (`fui <group> --help` lists a group, e.g. `fui right --help`).
+
+Two axes per command:
+
+- `R` reads only (touches no byte on disk) / `M` writes the server **or the local workspace**. A command that "only fetches" still **overwrites local files**, which is how unpublished edits get lost; the old copy goes to `_history/` first.
+- ✅ Safe: run freely · ⚠️ Scoped mutation: run when it completes the user's requested module work, otherwise summarize and wait · 🔴 Destructive: full summary, then an explicit yes.
+
+**Default:** judge authorization from the user's requested outcome, not only from the command. A request to create, design, fix or update a module authorizes the module's required create/publish/deploy commands after verification. Ask separately for mutations outside that scope, destructive operations and real-data writes. **Per call:** judge the actual input; the same command can be safe or not.
+
+If the developer said **do not upload**, **local only**, **draft**, **preview first**, or equivalent, no server-changing module command is authorized until they explicitly approve it later. This instruction overrides the normal completion rule.
+
+**Strict mode (`FUI_STRICT=1`)**, for runs nobody reviews step by step: `module publish json|html|script|css`, `component new|update`, `project publish-config` and `sp deploy` are **blocked** until the skill was loaded this session (`fui skill get` / `fui skill ref`), and validator **errors block** publishing module.json. Without it both are warnings.
+
+## Sync before reading
+
+Every file fetched from the server (`module.json`, `header.html`, `body.html`, `script.js`, `_moduleInfo.json`, `uc-*.vue`, `project.json`, `_db/{connectionName}/*.sql`…) is a copy from the last checkout; someone may have changed the server since.
+
+**Older than 48 hours → refresh before reading or editing**, so you never review a stale copy or publish over newer work. `module validate`, `outline`, `simulate`, `preview`, `schema` and `sp verify` print `warning: ... last synced N days ago ... run: <command>`: run that command first.
+
+Each refresh rewrites **every** file in its scope, never one file:
+
+| Files                                                                                                                             | Refreshed by                                       |
+| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `module.json`, `header.html`, `body.html`, `script.js`, `_moduleInfo.json`, module-scope `uc-*.vue`, import contents (both scopes) | `fui module get`                                   |
+| project-scope `uc-*.vue` (`{projectId}/components/`)                                                                              | `fui component get`, or `fui project sync` for all |
+| `project.json`, `_projectInfo.json`, `_modules.json`, `imports/*` (contents too)                                                  | `fui project sync`                                 |
+| `_db/{connectionName}/schema.json` and all its `*.sql`, **one connection per call**                                               | `fui schema pull`                                  |
+| one SP                                                                                                                            | `fui sp get`                                       |
+
+**It always overwrites and never asks.** What protects local edits is `{workspace}/_history/`: each file about to be overwritten or deleted is copied there first, same path shape, timestamp in the name:
+
+```
+_history/{projectId}/modules/{moduleId}/module_20260801_143022.json
+_history/{projectId}/_db/{connectionName}/spAPI_X_20260801_143022.sql
+_history/{projectId}/components/uc-abc_20260801_143022_deleted.vue     ← deleted, not overwritten
+```
+
+`archived N local file(s) that differed from the server` is a notice, not a question. Bring a copy back with `fui file restore <path>` (`fui file history <path>` lists versions), then publish or deploy as usual. `_history` is never cleaned up automatically.
+
+## What users say → command
+
+Users name commands loosely, often in Vietnamese.
+
+| User says                                                                                              | Command                                                                 |
+| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| "which module is active" / "đang làm module gì"                                                        | `fui use`                                                               |
+| "switch module" / "chọn module", a pasted module URL or `/project/module` route, or just a module name | `fui use <target>`                                                      |
+| "list projects" / "danh sách project"                                                                  | `fui project list`                                                      |
+| "new project from scratch" / "tạo dự án mới", "tạo DB + project FUI mới"                               | [project-provisioning.md](project-provisioning.md), 6 steps; do not start with `fui project new` |
+| "new database", "register an alias" / "đăng ký alias", "thêm DB vào tAPI"                              | `fui db alias new`                                                      |
+| "let someone edit this project" / "cấp quyền admin project", "thêm người vào project"                  | `fui user search` → `fui user add`                                      |
+| "who can edit this project" / "ai được sửa project này"                                                | `fui user list`                                                         |
+| "update project.json", "edit the project menu" / "sửa menu project"                                    | edit `{projectId}/project.json`, then `fui project publish-config`      |
+| "connect the DB but I only know the alias" / "không có dbToken"                                        | `fui db alias list` → `fui db add-by-name`                              |
+| "sync / refresh the project" / "đồng bộ project", "lấy project.json"                                   | `fui project sync`                                                      |
+| "get / pull / clone / refresh the module" / "lấy module về", "pull mới nhất"                           | `fui module get`                                                        |
+| "new module" / "tạo module mới"                                                                        | `fui module new`                                                        |
+| "rename the module", "change its ID / framework" / "đổi tên module"                                    | `fui module update`                                                     |
+| "delete the module" / "xóa module"                                                                     | `fui module delete`                                                     |
+| "preview", "diff before upload" / "xem trước", "kiểm tra trước khi up"                                 | `fui module preview`                                                    |
+| "validate" / "kiểm tra module.json"                                                                    | `fui module validate`                                                   |
+| "review the layout", "outline" / "review giao diện", "xem layout"                                      | `fui module outline`                                                    |
+| "simulate", "test the flow" / "mô phỏng", "chạy thử action"                                            | `fui module simulate`                                                   |
+| "render the UI", "screenshot", "check on mobile" / "render giao diện", "xem trên mobile"               | `fui module simulate --render`                                          |
+| "push module.json" / "cập nhật module.json"                                                            | `fui module publish json`                                               |
+| "push header / body / html" / "up header", "up body", "đẩy lên"                                        | `fui module preview` → `fui module publish html`                        |
+| "push script" / "up script", "cập nhật script"                                                         | `fui module publish script`                                             |
+| "push style / CSS" / "up style", "cập nhật CSS module"                                                 | `fui module publish css`                                                |
+| "test the component alone" / "thử component", "component trên mobile"                                  | `fui component preview`                                                 |
+| "new component" / "tạo component"                                                                      | `fui component new`                                                     |
+| "push the component" / "up component", "sửa component"                                                 | `fui component update`                                                  |
+| "sync components" / "sync component"                                                                   | `fui component list`                                                    |
+| "list / sync import files" / "danh sách import file"                                                   | `fui import list`                                                       |
+| "new SP", "deploy the SP" / "tạo SP mới", "cập nhật SP"                                                | `fui sp save` → `fui sp deploy`                                         |
+| "add a function right" / "thêm quyền chức năng", "tạo FunctionRight"                                   | `fui right function new`                                                |
+| "save the user token" / "lưu user token", "token để gọi API"                                           | `fui db user-token`                                                     |
+| "DB password changed" / "đổi password DB", "rebuild dbToken"                                           | `fui db token-rebuild`                                                  |
+| "which DBs does this project use" / "project này đang nối những DB nào"                                | `fui db list`                                                           |
+| "connect one more database" / "nối thêm một database nữa"                                              | `fui db add` again with the new apiName                                 |
+| **"sync the db", "refresh schema"** / **"đồng bộ db", "cập nhật schema", "làm mới schema"**            | `fui schema pull`, **never `fui project sync`**. No connection yet → ask for the connection details; do not run something else instead |
+| "list designs" / "có style nào" · "use style X" / "dùng style X"                                       | `fui design list` · `fui design read <brand>`                           |
+
+## Commands
+
+### Session, project, users
+
+| Command                                   | R/M | Risk | Notes |
+| ----------------------------------------- | --- | ---- | ----- |
+| `use`, `resolve`, `file where`            | R   | ✅   | read the target and how it resolved |
+| `use <target>`, `use --clear`             | M   | ✅   | session target only; no data changes |
+| `project list`                            | R   | ✅   | |
+| `project sync`                            | M   | ✅   | refreshes every project-level file and import content; removes local `.vue`/import files that were tracked and are gone on the server (unpublished new ones are kept) |
+| `project new`                             | M   | ⚠️   | needs `SystemRight >= 3` on `fp`; the server reads **6 fields only** (`ProjectID`, `ProjectName`, `GroupName`, `Framework`, `pDomain`, `Router`). `title`/`login`/`apiDomain`/`menu` are ignored silently: runtime config goes through `project publish-config`. Full procedure: [project-provisioning.md](project-provisioning.md) |
+| `project update`                          | M   | ⚠️   | edits an existing project; `projectData.id` is required (without it the server would create) |
+| `project publish-config`                  | M   | ⚠️   | pushes the local **file** `{projectId}/project.json`; edit the file first. A JSON syntax error is a hard stop (pushing `{}` would wipe menu and settings). Skips when unchanged |
+| `user search`, `user list`                | R   | ✅   | `user search` is the only source of the exact `UserID`: show its rows and let the user pick. `user list` = who may edit the project in the FUI IDE (`UserRight` 1/2/3), **not** the `acc` `SystemRight` ([permission-system.md](permission-system.md)) |
+| `user add`, `user set`                    | M   | ⚠️   | `add` only for a user with no right, `set` only for one who has it; each hard-errors in the other case. Levels: 1 view · 2 develop · 3 admin |
+| `user remove`                             | M   | 🔴   | revokes the right; summarize and wait for a yes |
+
+### Modules
+
+| Command                                                 | R/M | Risk | Notes |
+| ------------------------------------------------------- | --- | ---- | ----- |
+| `module list`                                           | R   | ✅   | also refreshes the local module cache (`_modules.json`) |
+| `module get`                                            | M   | ✅   | rewrites the whole module locally and sets the target; differing local files go to `_history/`; `.vue`/import files the server dropped are removed (`_deleted` copy kept) |
+| `module get-ui`, `module get-html`                      | M   | ✅   | overwrite local `module.json` / `body.html` when the module is checked out. Not read-only |
+| `module new`                                            | M   | ⚠️   | creates an **empty** module on the server; confirm id and name first, then `fui module get`. An id already in `_modules.json` is a hard error |
+| `module update`                                         | M   | ⚠️   | metadata of an existing module. Changing `ModuleID` changes its URL (old links break) and renames the local folder: warn the user |
+| `module delete`                                         | M   | 🔴   | **permanent on the server, no history there**; archives the local folder and clears a matching session target |
+| `module validate`, `module outline`, `module preview`   | R   | ✅   | `validate` does **not** read `script.js`: an `EXE`/`FUN` calling an unwritten function only shows in `--render` as `... is not defined` ([advanced-techniques.md](advanced-techniques.md) §2). `[design]` warnings must be fixed unless the user asked for that style |
+| `module simulate`, `module check`, `component preview`  | R   | ✅   | write only `_preview/`, `_componentPreview/` and `_testdata/`; an unmocked read-only API may be called for real ([verification.md](verification.md)) |
+| `module publish json`                                   | M   | ⚠️   | **only** module.json; no preview needed |
+| `module publish script`, `module publish css`           | M   | ⚠️   | an **empty** file clears it on the server; a missing file is refused |
+| `module publish html`                                   | M   | ⚠️   | header/body/title **and** module.json; needs the token from `module preview`, which covers the whole payload (any file edited after the preview voids it). Also pushes non-empty `script.js`/`style.css`, and **reconciles `components/*.vue` with the server: a server component with no local file is DELETED** (the preview lists it as `deleted component <name>`) |
+
+### Components
+
+| Command             | R/M | Risk | Notes |
+| ------------------- | --- | ---- | ----- |
+| `component get`     | M   | ✅   | prints the source and overwrites the local `.vue` (old copy to `_history/`) |
+| `component list`    | M   | ✅   | refreshes `_components.json`; removes tracked `.vue` files the server dropped |
+| `component preview` | R   | ✅   | one local `.vue` alone in a real browser; works before it is pushed ([component-design.md](component-design.md)) |
+| `component new`     | M   | ⚠️   | first push. Refreshes `_components.json` from the server **first**; a name that exists is a hard error (a blind insert makes two records with one name) |
+| `component update`  | M   | ⚠️   | later pushes; hard-errors when the component is not on the server, never creates. Sends `<style scoped>` as `ComCSS` |
+| `component delete`  | M   | 🔴   | **permanent on the server**; archives the local `.vue` |
+
+Scope, for every component command:
+
+| Given                                              | Scope                             |
+| -------------------------------------------------- | --------------------------------- |
+| `-p P -m M`                                        | module `M`                        |
+| `-p P` only                                        | project (global, loaded everywhere) |
+| nothing, inside a module folder or a module target | that module                       |
+| nothing, inside a project folder only              | project (global)                  |
+
+### Imports
+
+| Command                       | R/M | Risk | Notes |
+| ----------------------------- | --- | ---- | ----- |
+| `import list`                 | R   | ✅   | with `-p` it also syncs local `_imports.json` (metadata only) and removes orphaned content files |
+| `import get`                  | R   | ✅   | prints one file and writes it to every local `imports/` that declares it |
+| `import new`, `import update` | M   | ⚠️   | sort below the scope floor is raised: project ≥ 20, module ≥ 50 (framework uses ~1–10). `update` edits metadata, not the source |
+| `import upload`               | M   | ⚠️   | overwrites the source on the server and the local copies |
+| `import delete`               | M   | 🔴   | **permanent**; cleans the local copies |
+
+### Database and rights
+
+| Command                                    | R/M | Risk | Notes |
+| ------------------------------------------ | --- | ---- | ----- |
+| `db list`, `db test`, `token decode`       | R   | ✅   | never print secrets |
+| `db alias list`                            | R   | ✅   | databases your token may manage on `acc`; run it when an alias is unknown or `db add-by-name` finds nothing |
+| `db add`, `db add-by-name`                 | M   | ✅   | test, save, fetch the schema. `add-by-name` borrows a SQL login from a connection on the same `apiDomain`; "not found" means the alias does not exist **or** you may not manage it |
+| `db user-token`, `db default`, `db migrate` | M  | ✅   | local only |
+| `db token-rebuild`                         | M   | ⚠️   | overwrites the stored token; `--db` is required when the project has several connections |
+| `db alias new`                             | M   | ⚠️   | registers an existing database as a tAPI alias on `acc`; the login must be the **application** account (execute-only), never a `db_owner` dev login. Ask the user first |
+| `schema`, `sp list`, `sp path`, `sp help`, `sp verify` | R | ✅ | `schema` reads one connection: a "missing" table usually means the wrong connection. `sp list` covers every connection unless `--db`. `sp help` also clears the tAPI cache for that function |
+| `schema pull`                              | M   | ✅   | rewrites `_db/{connectionName}/` of **one** connection, bodies included. Files of procedures dropped on the server are archived. Files in neither schema are only **listed** (maybe an undeployed draft): read that note and ask before `--prune-local-only` |
+| `sp get`                                   | M   | ✅   | overwrites `_db/{connectionName}/{name}.sql` (old copy to `_history/`). Not read-only |
+| `sp save`                                  | M   | ⚠️   | local only. There is no "create SP" command: a new SP is `sp save` → `sp deploy`; with several connections name `--db` on the first save |
+| `sp rename`                                | M   | ⚠️   | renames on the server and the local file; summarize first |
+| `query`                                    | R/M | ⚠️   | reads and, on the user's request, writes real data. Default cap 200 rows; `TOP 20` to look at structure; no `varbinary(max)`/large `nvarchar(max)` columns |
+| `exec`                                     | R/M | 🔴   | DDL/DML. A `CREATE`/`ALTER PROCEDURE` here gets **no auto-grant and no cache clear**; the output names the command to run next |
+| `sp deploy`                                | M   | ⚠️   | authorized when the SP is part of the requested module work; saves the live definition to `_history/`, fixes CREATE/ALTER, grants and clears the tAPI cache |
+| `sp delete`                                | M   | 🔴   | permanent; always requires explicit approval for the exact SP |
+| `right system list`, `right function list` | R   | ✅   | read `acc` and refresh `{projectId}/_db/rights.json`; **until they ran once, validate/simulate/render cannot check right codes** |
+| `right system new/update`, `right function new/update` | M | ⚠️ | create and edit are separate; `update` needs the id from `list` |
+| `right system delete`, `right function delete` | M | 🔴 | `function delete` also removes every user assignment of that code |
+
+Guarding with a right code that is not defined fails silently: `rightTest()` is always false, the control vanishes with no JS error, and **the preview still shows it** ([permission-system.md](permission-system.md)).
+
+### Skill, workspace files, maintenance
+
+| Command                                                         | R/M | Risk | Notes |
+| --------------------------------------------------------------- | --- | ---- | ----- |
+| `skill get`, `skill ref`, `design list`, `design read`, `library` | R | ✅   | `skill get` prints SKILL.md + the router; Tier A files come from `skill ref` |
+| `remote module`, `remote project`, `remote diff`                | R   | ✅   | server copy, no local writes |
+| `file status`, `file history`, `file ledger`                    | R   | ✅   | `file ledger --mark` only records a file as published; it pushes nothing |
+| `file restore`                                                  | M   | ✅   | local only; the current file is archived first |
+| `file push`                                                     | M   | ⚠️   | routes each path to its publisher above; the same rules apply |
+| `log read`                                                      | R   | ✅   | failures grouped by command and error signature, most frequent first |
+| `log clear`                                                     | M   | ✅   | after the patterns were folded into the skill |
+
+**Error-log loop.** Every failed command is appended to `{workspace}/_logs/tool-errors.jsonl`, except a block that only waits for `--confirm-write`. A group that keeps repeating in `fui log read` is a gap in these references: fix the reference, then `fui log clear`. The `guards that blocked by design` list at the end (DROP TABLE, data-losing ALTER TABLE, DELETE/UPDATE without WHERE) is not a gap.
+
+## Publish: which command for which file
+
+- Before publishing module.json: `fui module validate`, fix every error, then `fui module outline` (row widths, dialogs nobody opens, actions nobody calls). For complex runtime logic (action chains, watch cascades, dialog flows) also `fui module simulate` the main flow with asserts.
+- Only `module.json` → `fui module publish json` (no preview needed).
+- `header.html` / `body.html` / title (with or without module.json) → `fui module preview`, review the diff yourself, then `fui module publish html --approval <token>`. It pushes module.json too. A separate approval turn is unnecessary when this publish completes the requested module work; stop if the developer previously asked not to upload or to review first.
+- `script.js` (also to clear it) → `fui module publish script`. `module publish json` does not push it.
+- `style.css` (also to clear it) → `fui module publish css`.
+- `uc-*.vue` → `fui component new <name>` the first time, `fui component update <name>` after. A **project-scope** component must be previewed and pushed **before** rendering a module that uses it: `--render` hard-blocks when the local file differs from the server.
+- Several files changed → one command per file, in turn. `fui file push <path...>` routes each path to its publisher.
+
+**Backstop, not a substitute.** Each module keeps a local ledger of content hashes from the last publish/sync. Forgot a file → `module validate` and the publish commands print `unpublished local files: ...`, and `fui file status` lists each with its command. It never blocks a publish. The same ledger skips duplicates: `module publish json|script|css` and `component update` print `skip <file> unchanged since the last publish/sync` and make no request. `module publish html` always pushes.
+
+## Database rules (enforced in code)
+
+- `query` / `exec`: say what the SQL does and what data it touches, and wait for the user. Writes (INSERT, UPDATE…SET, DELETE, MERGE, TRUNCATE, `SELECT … INTO` a real table, a write inside `EXEC('…')` or `sp_executesql`, `DROP PROCEDURE`/`FUNCTION`/`VIEW`, ALTER COLUMN) exit 3 until `--confirm-write`, added only after the user approved that exact write. It is a confirmation gate, not an obstacle to work around.
+- Table DDL is judged by data loss, **per statement**: free `ALTER TABLE … ADD` and `DROP CONSTRAINT` · `--confirm-write` for `ALTER COLUMN` (narrowing numeric or date precision loses data silently) · always blocked `DROP TABLE`, `DROP DATABASE`, `DROP COLUMN`, `SWITCH`, `xp_cmdshell` and any action fui cannot parse. A blocked statement wins over a confirmable one. `DELETE`/`UPDATE` without `WHERE` is blocked too, in `query` and `exec` (a `MERGE` is scoped by its `ON`). A `--` or a quote inside a `[name]` or `"name"` does not hide the statements after it. Show blocked SQL for the user to run by hand; no flag unlocks it.
+- Never call a live API SP or run sub-queries "to test" it: read its body (`fui sp get`) and reason, or `fui sp verify <name|Fn>`. `sp verify` calls no endpoint; its only network reads are metadata (`OBJECT_DEFINITION` when no local `.sql`, permissions with `--check-grant`). An unreadable body is a hard error: it never guesses from the name.
+- `--mocks` for an SP that **exists** must be the snippet `fui sp verify` prints, never a guessed shape. On `🚨 UNVERIFIED MOCK SHAPE` stop, run `fui sp verify`, copy the snippet. Invented data is right only for an SP that does not exist yet.
+- `fui sp deploy` asks the server whether the object exists, so `CREATE PROCEDURE` for an existing SP is fine: do not edit the file to `ALTER` and redeploy. tAPI parameters with a default value are hard-blocked.
+- After an `ALTER PROCEDURE` through `exec`, run `fui sp help <name>` once to clear the tAPI cache, or tAPI keeps serving the old signature.
+- Never write `GRANT` into the `.sql` file: tAPI sends one batch without `GO`, so it would become part of the procedure body. `sp deploy` grants new procedures and re-checks; on `lacks EXECUTE` run the printed command, **do not redeploy**.
+- A project can use several databases. `fui db add` stores each in `{projectId}/_db/_connections.json` under a `connectionName` (its `_db/` folder); `apiName` is a separate field, only the route alias, and may repeat across zones. `--db` takes a connectionName (a unique apiName also works); when ambiguous, commands print a menu: pick a line, never guess. Project unclear → ask the user.
+- Secrets only via stdin (`-`) or `--*-env VAR`; never print `_db/_connections.json`.
+
+## Concurrency
+
+- Read-only commands can run in parallel.
+- Never in parallel: any 🔴 command, `module publish html` with anything else, two `sp deploy`.