@dforge-core/dforge-mcp 0.2.15 → 0.2.17

package/skills/dforge-mcp-author/references/security.md

@@ -213,7 +213,7 @@ Lives in: `ui/folders.json`
 
 | Property | Type | Description |
 |---|---|---|
-| `viewName` | string | Default data view (usually `"default"`) |
+| `viewName` | string | Entity view to bind — a key under the entity's `views` (see [Column-level security](#column-level-security-entity-views)), **not** a `ui/data_views.json` code. `"default"` means "no view" (full column set). |
 | `quickAdd` | boolean | Show "+" quick-add button (`true` for main entities, `false` for detail/line items) |
 | `rowFilter` | object | Row-level filter scoping which records are visible in this folder |
 
@@ -226,6 +226,82 @@ Row filters use a compact filter object with:
 
 This is how **row-level security** works in the module package — subfolders with `rowFilter` restrict which rows are visible. Users assigned to "Central Warehouse" only see stock where `warehouse_id = 2001`.
 
+## Column-level security (entity views)
+
+> Worked example: `dforge://example/column-security/` — one entity, two folders, two
+> column sets. Its README walks the overrides and the ways a view fails the install.
+
+Layer 2 of the model. A **entity view** is a named subset of an entity's columns, declared on the entity itself; a folder binds one per entity. Users working in that folder see **only** the columns the view lists — the rest are neither visible nor queryable there.
+
+Two halves, both required:
+
+| File | Key | Effect |
+|---|---|---|
+| `entities/<entity>.json` | `views.<viewName>.columns` | Declares the view and its column set |
+| `ui/folders.json` | `entities.<code>.viewName` | Binds that view for this entity in this folder |
+
+```json
+{
+    "fields": { "product_id": {}, "name": {}, "price": {}, "cost": {}, "quantity": {} },
+    "views": {
+        "accountant": {
+            "columns": {
+                "product_id": {},
+                "name": { "flags": "V" },
+                "price": { "flags": "VE" },
+                "cost": { "flags": "V" }
+            }
+        },
+        "storekeeper": {
+            "columns": {
+                "product_id": {},
+                "name": { "flags": "V" },
+                "quantity": { "flags": "VE" }
+            }
+        }
+    }
+}
+```
+
+```json
+"entities": { "product": { "viewName": "accountant", "quickAdd": true } }
+```
+
+The storekeeper folder cannot see `price` or `cost` at all — not on screen, not through a filter, not in an export.
+
+**Per-column overrides** (all optional, each falls back to the entity-level value): `flags`, `orderNum`, `isNullable`, `editMask`, `displayFmt`, `refFilter`, `params`, `formula`. `{}` means "expose this column, override nothing".
+
+> **An empty override is a value, not an absence.** The runtime merges view over entity with `COALESCE`, which skips NULL only — so `"flags": ""` means "no flags in this view" (a column neither visible nor editable) and `"params": {}` suppresses the entity-level params rather than inheriting them. Omit the key entirely to inherit — `"flags": null` fails schema validation. See `flags.md` for the flag letters.
+
+> **`M` works in a view override too**, folding into that override's `isNullable`. Since a view writes no DDL, the requiredness is runtime-only — which is how a column nullable in the database is made mandatory inside one view: `{ "flags": "VEM" }`. The fold is one-directional: dropping `M` does not loosen the column, because `isNullable` still inherits. See `flags.md` → Per-view overrides.
+
+`formula` lets one view compute a column differently from the entity — same DSL as a field's `formula`, and **only on a column the entity declares as `columnType: "F"`**; elsewhere the install fails, because there that field holds the SQL default and a view cannot change a physical column's `DEFAULT`. There is no per-view default value for a normal column. See `formulas.md`.
+
+### Rules the installer enforces
+
+Each of these is an install-time error, and each is silent at runtime if it slips through — which is why `dforge_module_validate` checks them offline:
+
+- A column absent from `columns` is **hidden**. That is the mechanism, not an oversight.
+- A view must list the entity's **primary key** — records are addressed by it. To keep it off screen, drop `V` from its flags instead of omitting it.
+- A column code that doesn't exist on the entity, a view with **no columns**, the same column listed twice under different casing, or two views on one entity whose names differ only by case (a folder binds case-insensitively, so only one could ever be reached).
+- Views must be declared on the entity's **own** module. An `extends` extension declaring `views` is rejected — a view enumerates the complete column set, which an extension does not own.
+- A `viewName` that no view declares, or one naming a view with no columns, **fails the install**. It does not fall back: the fallback is the entity's full column set, so a typo would quietly *unrestrict* the folder.
+- Columns removed from a view are reaped on upgrade — that is the security change the author asked for. Whole views are not: `entity_view` also holds tenant views from the card-layout editor, and the installer cannot tell them apart.
+
+### `"default"` is the one exempt name
+
+`"viewName": "default"` means **no view** (full column set) and declares nothing. It is what every shipped module writes, and what the runtime auto-creates for an entity reached without a folder binding — so it is exempt from the checks above. A module that really declares a view named `default` still gets it bound.
+
+### Don't confuse the three "views"
+
+| Term | Where | What it is |
+|---|---|---|
+| **Entity view** | `entities/*.json` → `views` | Column-level security (this section) |
+| **Data view** | `ui/data_views.json` | A grid / kanban / calendar over an entity (`data-views.md`) |
+| **SQL view** | `entities/*.json` → `isView` + `viewSql` | An entity backed by a SQL view instead of a table |
+
+`viewName` in `folders.json` binds the first. Menus' `dataViewCode` references the second.
+
 ### When to use subfolders
 
 - **Multi-location modules** (warehouses, offices, branches) — one subfolder per location, filtered by location FK

package/skills/dforge-mcp-author/references/validation-checklist.md

@@ -105,6 +105,8 @@ For each entity:
 ## Security
 
 - [ ] `security/roles.json` exists (at least one role)
+- [ ] Every entity view (`views.<v>.columns` on an entity) lists the entity's **primary key**, names only real columns, and has at least one column — each of these fails the install
+- [ ] Every `viewName` in `ui/folders.json` is either `"default"` (= no view) or a view that entity actually declares — an unresolved name fails the install rather than falling back
 - [ ] Every role has `description` and `rights` (both required; no `label` field in `roles.json` — the `roles.schema.json` sets `additionalProperties: false`, so any extra field including `label` is rejected here). `description` is the English display-name fallback; **localized role labels live in the translation files** (`roles.<code>.label`) and are completeness-enforced — see Translations below.
 - [ ] The field name is `rights`, NOT `entityRights`
 - [ ] Rights strings use only valid letters: `SIUDC` for entities, `E` for actions/reports/folders

package/skills/dforge-module-build/SKILL.md

@@ -31,6 +31,7 @@ flags, or column patterns.
 | Add a grid / list view | `dforge://reference/data-views`, `dforge://example/ui/data_views.json` | — |
 | Add a matrix (pivot) view | `dforge://reference/data-views` (§Matrix), `dforge://example/matrix-budget/ui/data_views.json`, `dforge://example/matrix-budget/entities/budget_line.json` | — |
 | Add kanban / calendar / tree-grid / master-detail | `dforge://reference/data-views` | `dforge://schema/data-views` |
+| Hide columns from a user type (column-level security) | `dforge://reference/security` (§Column-level security), `dforge://example/column-security/entities/product.json`, `dforge://example/column-security/ui/folders.json` | — |
 | Add a menu | `dforge://reference/menus`, `dforge://example/ui/menus.json` | — |
 | Add an action | `dforge://reference/action-dsl`, `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json` | `dforge://docs/dsl` |
 | Add a trigger | — | `dforge://schema/triggers`; condition syntax in `dforge://docs/dsl` |
@@ -186,7 +187,13 @@ before committing, then `dforge_action_add`. One action per turn.
 
 **2b Triggers** reference actions that must already exist. `async: true` runs
 after the transaction commits (use for anything slow); `async: false` runs
-in-transaction, so a failure rolls back the original change.
+in-transaction, so a failure rolls back the original change — **including on
+another module's entity**. A bridge's `async: false` trigger vetoes its host's
+write, exactly as a mandatory extension column already refuses one, so pick it
+to enforce an invariant, not merely to react: a bug in the action blocks the
+host's workflow as effectively as a real violation. Keep such an action to the
+check itself and put everything else behind `try`/`catch` or in an
+`async: true` trigger.
 
 **2c Jobs** run as the system user with **no current record** — the action must
 not use `[field]` syntax. Wrap a record-context action in a thin job action that
@@ -204,8 +211,11 @@ per entity, so you'll often `view_modify` rather than `view_add`.
 
 View codes are semantic — the entity name (`feedback_item`), a plural
 (`invoices`), or descriptive (`invoices_kanban`). **Never use the literal code
-`default`**; `ui/folders.json`'s `viewName: "default"` is a fallback alias the
-platform resolves to the entity's first declared view.
+`default`.** Note that `ui/folders.json`'s `viewName` is a different axis
+entirely: it binds an *entity view* (column-level security, declared under
+`views` on the entity file), not a data view code. `"default"` there means "no
+entity view — show the full column set", and any other name the entity does not
+declare **fails the install**. See `references/security.md`.
 
 Then wire menus with `dforge_menu_add` — a section node per group, leaves
 pointing at the views.
@@ -273,6 +283,13 @@ stated trigger; every report's params sit on a dataset.
 4. **Show the rights matrix as a table** (rows = entities/actions/reports,
    columns = roles, cells = rights strings), each cell explained by the verb it
    maps to. Get sign-off.
+5. **Column-level security only when the intake asks for it.** Roles grant rights
+   per entity, not per field. When a user type must not see specific *columns*
+   (salaries, cost prices, personal data), that is an **entity view**: declare
+   `views.<name>.columns` on the entity and bind it with `viewName` on the folder
+   that user type works in. Don't reach for it otherwise — a view is the complete
+   column list, so it is one more list to keep in step with the fields. Rules and
+   the worked example: `references/security.md` → Column-level security.
 5. `dforge_role_add` for new roles; `dforge_role_right_set` per grant when
    amending an existing one.