@dforge-core/dforge-mcp 0.2.14 → 0.2.16

package/resources/docs/dsl-reference.md

@@ -14,7 +14,8 @@ params:
 
 canExecute:
     # Single-expression formula returning boolean
-    # Determines whether the action button is enabled for current record(s)
+    # Enables/disables the button AND is re-checked server-side on execute
+    # (see "canExecute is enforced, with a fail-open subset")
 
 onBeforeStart:
     # Pre-queue initialization (async / background actions only)
@@ -396,6 +397,62 @@ For "who did this", prefer the platform audit columns (`created_by` /
 predicates in `canExecute:` or a formula column, use `CURRENT_USER_ID()`, which
 the server translates to an exact `::bigint` SQL literal.
 
+> **The table above is about `execute:` (JavaScript).** The *formula* engine —
+> `canExecute:`, formula columns, filters, reports — keeps large integer literals
+> exact: the parser holds them as 64-bit integers and serializes anything past
+> 2^53 as text so the browser cannot round it. `canExecute: [owner_id] = 215117312238288897`
+> compares against the id you wrote. `CURRENT_USER_ID()` is still the better way to
+> say "mine" — it does not hard-code an id — but a literal is no longer a
+> correctness trap on that side.
+
+## canExecute is enforced, with a fail-open subset
+
+`canExecute:` is evaluated **twice**: by the browser to decide whether the button
+is **enabled** (the action stays in the toolbar, greyed out — it is not hidden),
+and by `action.execute` over every targeted record before any write. A
+record in the wrong state is refused with `ACTION_EXECUTION_FAIL`, so the predicate
+is a gate rather than a UI hint, and `canExecute: false` is the way to make an
+action fireable only by a trigger or a scheduled job (both invoke the script engine
+directly and bypass the check).
+
+**Both evaluators have gaps, and both fail open**, but not the same gaps. The
+server is a scalar walker and lets anything richer through. The client implements
+the whole documented formula function set, so ordinary functions evaluate there
+normally; it throws — and its `catch` **enables** the button — on ref navigation,
+on the set aggregates `SUM` / `COUNT` / `AVG` (deliberately not formula functions;
+counting belongs in a Generated `G` column), and on any name it does not know, a
+typo included — a `canExecute:` is never validated against the function set at
+install, so `TOADY()` ships and enables the button for every record.
+`$[setting]` references are a separate case again: they do not throw, the client
+resolver is stubbed to `null`, and the server has no settings resolver — so a
+settings-dependent guard is unenforced server-side and resolves unpredictably in
+the browser. Read settings in `execute:` instead.
+
+| tier | construct | client | server |
+|---|---|---|---|
+| 1 | **comparisons** (`=` `==` `!=` `<>` `>` `>=` `<` `<=`) between `[field]`s and literals, combined with `AND` / `OR` / `NOT`; a bare `true` / `false` | evaluates | **enforces** |
+| 2 | arithmetic, `IN`, `BETWEEN`, any formula function (`TODAY`, `IF`, `DATEADD`, `REGEX_MATCH`, `CURRENT_USER_ID`, …) | evaluates | fail-open |
+| 3 | ref navigation, `SUM` / `COUNT` / `AVG`, any unknown function (a typo included) | **fail-open (throws)** | fail-open |
+| — | `$[setting]` references | **evaluates as null** (no throw) | fail-open |
+
+**A bare boolean column is not tier 1.** The walker evaluates conditions, not
+values — a `[field]` resolves only as an operand of a comparison — so
+`canExecute: [is_active]` and `canExecute: NOT [is_blocked]` fail open. Write
+`[is_active] = true` and `NOT ([is_blocked] = true)`. A bare `false` is fine: it is
+a complete condition, which is what makes the `canExecute: false` idiom work.
+
+Tier 1 + tier 2 is the normal shape and behaves correctly: the client evaluates the
+whole predicate so the button state is right, and the server short-circuits `AND` /
+`OR` so the tier-1 half is still enforced.
+
+**Tier 3 is what breaks.** The server short-circuits, the client does not, so
+`[status] = 'Pending' AND COUNT([lines]) > 0` on a non-`Pending` record still
+evaluates `COUNT` in the browser, throws, and the button is **enabled** — then the
+server refuses the call. A `canExecute:` is not validated against the function set
+at install, so that spelling ships silently. Count with a `G` column and compare the
+scalar; denormalise instead of navigating; put the rest in `execute:` behind
+`error()`.
+
 ### Messaging & notifications
 
 #### `info(message, opts?)`, `warn(message, opts?)`

package/resources/schemas/entity.schema.json

@@ -95,10 +95,88 @@
 				}
 			},
 			"additionalProperties": true
+		},
+		"views": {
+			"type": "object",
+			"description": "Entity views keyed by view name — column-level security. Unrelated to 'isView'/'viewSql' (a SQL-view-backed entity) and to ui/data_views.json (grids, kanban, calendars). A folder binds one view per entity via ui/folders.json (entities.<code>.viewName); users working in that folder see ONLY the columns the view lists. Entities without views (or folders naming a view that isn't declared here) show the entity's full column set.",
+			"propertyNames": {
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$",
+				"maxLength": 100
+			},
+			"additionalProperties": {
+				"$ref": "#/$defs/entityView"
+			}
 		}
 	},
 	"additionalProperties": false,
 	"$defs": {
+		"entityView": {
+			"type": "object",
+			"description": "One entity view: the columns it exposes, plus optional per-view overrides on each.",
+			"required": ["columns"],
+			"properties": {
+				"columns": {
+					"type": "object",
+					"description": "Column code -> per-view overrides. Columns absent from this map are hidden in a folder bound to this view. Use {} (or null) to expose a column with no overrides. Must include the entity's primary key column(s) — records are addressed by them; hide the key from the UI by omitting 'V' from its flags instead.",
+					"minProperties": 1,
+					"propertyNames": {
+						"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+					},
+					"additionalProperties": {
+						"$ref": "#/$defs/entityViewColumn"
+					}
+				},
+				"params": {
+					"type": "object",
+					"description": "Free-form view configuration, stored on entity_view.params.",
+					"additionalProperties": true
+				}
+			},
+			"additionalProperties": false
+		},
+		"entityViewColumn": {
+			"description": "Per-view overrides for one column. Every property is optional; anything omitted falls back to the entity-level value on the column itself.",
+			"type": ["object", "null"],
+			"properties": {
+				"flags": {
+					"type": "string",
+					"maxLength": 10,
+					"pattern": "^[VIEM]*$",
+					"description": "Flag letters for this column in this view — the same V/I/E/M vocabulary as a field's 'flags'. One rule, three cases: OMIT the key to inherit the entity-level flags (omission is the only inherit spelling — this field is a string, so a literal null does not validate; to inherit everything, set the whole column override to null or {}); any string, empty included, OVERRIDES them, because the runtime merges view over entity with COALESCE, which skips a missing value only; and a non-empty string REPLACES the entity letters rather than merging with them. So 'V' exposes the column read-only (visible, not editable) however the entity flagged it, and '' means 'no flags here' — neither visible nor editable. M works here as it does on a field: the installer folds it into this override's isNullable, making the column required IN THIS VIEW even when it is nullable in the database (a view writes no DDL, so the requiredness is runtime-only). Declaring M together with \"isNullable\": true is rejected at pack time. Note the fold is one-directional — DROPPING M from a view's flags does not make a column optional, because isNullable still COALESCEs to the entity value; write \"isNullable\": true to loosen it."
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Display order within this view."
+				},
+				"isNullable": {
+					"type": "boolean",
+					"description": "Nullability override for this view."
+				},
+				"editMask": {
+					"type": "string",
+					"maxLength": 100
+				},
+				"displayFmt": {
+					"type": "string",
+					"maxLength": 100
+				},
+				"refFilter": {
+					"type": "object",
+					"description": "Lookup filter override for a reference column in this view.",
+					"additionalProperties": true
+				},
+				"formula": {
+					"type": "string",
+					"description": "Formula override for this column in this view, in the same DSL as a field's 'formula'. Allowed only on a column the entity declares as columnType 'F'; on any other column the install FAILS (it does not silently ignore the override), 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 today. The runtime prefers it over the entity-level formula, so one view can compute a column differently from the entity. The parsed AST is regenerated at install; a formula that does not parse, calls an unimplemented function, or aggregates over a 1:N set fails the install (each renders empty at runtime)."
+				},
+				"params": {
+					"type": "object",
+					"description": "Control-specific configuration override for this view.",
+					"additionalProperties": true
+				}
+			},
+			"additionalProperties": false
+		},
 		"field": {
 			"type": "object",
 			"description": "Entity column/field definition",
@@ -129,8 +207,8 @@
 				},
 				"flags": {
 					"type": "string",
-					"pattern": "^[VIEMH]*$",
-					"description": "Display flags: V=Visible, I=Identity, E=Editable, M=Mandatory, H=Hidden. M is resolved into isNullable:false at install, so it makes the column NOT NULL; it is inert on virtual (R/S/F) and identity columns. Declaring M together with isNullable:true is rejected at pack time."
+					"pattern": "^[VIEM]*$",
+					"description": "Column flags, in any order. V=Visible and E=Editable are display/interaction; I=Identity marks a platform-managed column (never user-editable, excluded from required validation); M=Mandatory is not a runtime flag at all — it is resolved into isNullable:false at install, so it makes the column NOT NULL, is inert on virtual (R/S/F) and identity columns, and declaring it together with isNullable:true is rejected at pack time. Any other letter is rejected at pack time; there is no H flag — a column is hidden by omitting V."
 				},
 				"isPk": {
 					"type": "boolean",

package/resources/schemas/folders.schema.json

@@ -58,7 +58,7 @@
 			"properties": {
 				"viewName": {
 					"type": "string",
-					"description": "Entity view name (data view code) to use in this folder. Common values include 'default'."
+					"description": "Entity view to bind for this entity in this folder — the name of a key under the entity definition's 'views' (column-level security), NOT a data view code from ui/data_views.json. Users in this folder then see only the columns that view lists. The conventional 'default' declares nothing and means 'no view' (full column set); any other name that the entity does not declare fails the install."
 				},
 				"quickAdd": {
 					"type": "boolean",

package/skills/dforge-mcp-author/examples/column-security/README.md

@@ -0,0 +1,67 @@
+# column-security — entity views example
+
+A minimal module whose only job is to demonstrate **entity views**: dForge's
+column-level security. One `product` entity holds both stock and pricing, and two
+folders show two different column sets of it.
+
+## The shape
+
+Column-level security is always **two halves**, and both are required:
+
+| Piece | File | Effect |
+|---|---|---|
+| The column set | `entities/product.json` → `views` | Declares `storekeeper` and `accountant` — each a named subset of the entity's columns |
+| The binding | `ui/folders.json` → `entities.product.viewName` | The Warehouse folder binds `storekeeper`, the Finance folder binds `accountant` |
+
+```
+product columns:  name  sku  quantity  cost_price  sale_price  margin
+
+Warehouse folder → view "storekeeper":  name  sku  quantity
+Finance folder   → view "accountant":   name  sku  quantity(read-only)  cost_price  sale_price  margin
+```
+
+A user working in Warehouse cannot see `cost_price` **at all** — not on screen, not
+through a filter, not in an export. The columns a view omits are invisible *and*
+unqueryable there. That is the mechanism: omission is the restriction.
+
+## What each view demonstrates
+
+- **`storekeeper`** — the plain case: list the columns this folder may see, and no
+  others. Note it still lists `product_id`; a view must include the primary key
+  because records are addressed by it.
+- **`accountant`** — the override cases:
+  - `"quantity": { "flags": "V" }` — visible but **not** editable here, while the
+    entity itself declares `VEM`. A per-column `flags` override re-flags the column
+    for the folders bound to this view only.
+  - `"margin": { "formula": "…", "displayFmt": "N1" }` — a per-view **formula**
+    override: the entity computes margin as an absolute amount, this view computes it
+    as a percentage. Allowed only because `margin` is a `columnType: "F"` column — on
+    any other column that field holds the SQL default, so the override would be inert
+    and the install rejects it.
+
+## Things that would fail the install
+
+Worth knowing, because each one is silent at runtime if it slips through:
+
+- Dropping `product_id` from a view — records the client cannot open or save.
+- A view with **no** columns, or a column code the entity doesn't have.
+- Two views whose names differ only by case — a folder binds case-insensitively, so
+  only one could ever be reached.
+- A `viewName` in `folders.json` that no view declares. This does **not** fall back:
+  the fallback would be the entity's full column set, so a typo would quietly
+  *unrestrict* the folder. `"default"` is the one exempt name and means "no view".
+
+`dforge_module_validate` checks all of these offline, before packing.
+
+## What this example deliberately leaves out
+
+The `product_grid` data view lists **every** column, including the prices. That is
+correct: a data view describes the presentation, and the folder's entity view decides
+what a user in that folder is allowed to see of it. The grid renders whichever
+columns survive the view — you do not maintain one data view per role.
+
+Entity views are also unrelated to the two other things called "view" here: a *data
+view* (`ui/data_views.json`) is a grid/kanban/calendar, and `isView` + `viewSql` on an
+entity means it is backed by a SQL view.
+
+See `dforge://reference/security` → Column-level security for the full rules.

package/skills/dforge-mcp-author/examples/column-security/entities/product.json

@@ -0,0 +1,79 @@
+{
+	"description": "Products, with stock and pricing on one record",
+	"dbObject": "product",
+	"toString": "{name}",
+	"traits": ["identity", "audit"],
+	"fields": {
+		"name": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "text",
+			"flags": "VEM",
+			"maxLen": 200,
+			"orderNum": 10,
+			"description": "Product Name"
+		},
+		"sku": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "text",
+			"flags": "VEM",
+			"maxLen": 40,
+			"orderNum": 20,
+			"description": "SKU"
+		},
+		"quantity": {
+			"dbDatatype": "numeric(18,2)",
+			"fieldTypeCd": "number",
+			"flags": "VEM",
+			"precision": 2,
+			"orderNum": 30,
+			"description": "Quantity On Hand"
+		},
+		"cost_price": {
+			"dbDatatype": "numeric(18,2)",
+			"fieldTypeCd": "currency",
+			"flags": "VEM",
+			"precision": 2,
+			"orderNum": 40,
+			"description": "Cost Price"
+		},
+		"sale_price": {
+			"dbDatatype": "numeric(18,2)",
+			"fieldTypeCd": "currency",
+			"flags": "VEM",
+			"precision": 2,
+			"orderNum": 50,
+			"description": "Sale Price"
+		},
+		"margin": {
+			"columnType": "F",
+			"fieldTypeCd": "currency",
+			"baseDatatypeCd": "number",
+			"flags": "V",
+			"precision": 2,
+			"formula": "[sale_price] - [cost_price]",
+			"orderNum": 60,
+			"description": "Margin"
+		}
+	},
+	"views": {
+		"storekeeper": {
+			"columns": {
+				"product_id": {},
+				"name": {},
+				"sku": {},
+				"quantity": {}
+			}
+		},
+		"accountant": {
+			"columns": {
+				"product_id": {},
+				"name": {},
+				"sku": {},
+				"quantity": { "flags": "V" },
+				"cost_price": {},
+				"sale_price": {},
+				"margin": { "formula": "([sale_price] - [cost_price]) / [sale_price] * 100", "displayFmt": "N1" }
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/manifest.json

@@ -0,0 +1,23 @@
+{
+	"packageFormat": 1,
+	"moduleId": "20000000-0000-0000-0000-000000000003",
+	"code": "column_security",
+	"version": "0.1.0",
+	"dbSchemaVersion": "0.0.1",
+	"displayName": "Column Security",
+	"description": "Example module demonstrating entity views — column-level security",
+	"author": { "name": "dForge Examples" },
+	"license": "MIT",
+	"category": "Examples",
+	"tags": ["example", "security", "entity-views"],
+	"icon": "bi-eye-slash",
+	"dependencies": {
+		"admin": ">=0.0.1"
+	},
+	"supportedLocales": ["en-US"],
+	"created": "2026-08-19",
+	"updated": "2026-08-19",
+	"entities": {
+		"product": "./entities/product.json"
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/security/roles.json

@@ -0,0 +1,16 @@
+{
+	"column_security.storekeeper": {
+		"description": "Counts stock; never sees cost or price",
+		"rights": {
+			"product": "SIU",
+			"folder:warehouse": "E"
+		}
+	},
+	"column_security.accountant": {
+		"description": "Owns costing and pricing",
+		"rights": {
+			"product": "SIU",
+			"folder:finance": "E"
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/translations/en-US.json

@@ -0,0 +1,35 @@
+{
+	"entities": {
+		"product": {
+			"label": "Product",
+			"fields": {
+				"name": { "label": "Product Name" },
+				"sku": { "label": "SKU" },
+				"quantity": { "label": "Quantity On Hand" },
+				"cost_price": { "label": "Cost Price" },
+				"sale_price": { "label": "Sale Price" },
+				"margin": { "label": "Margin" }
+			}
+		}
+	},
+	"folders": {
+		"warehouse": { "label": "Warehouse" },
+		"finance": { "label": "Finance" }
+	},
+	"roles": {
+		"column_security.storekeeper": { "label": "Storekeeper" },
+		"column_security.accountant": { "label": "Accountant" }
+	},
+	"views": {
+		"product_grid": { "label": "Products" }
+	},
+	"menus": {
+		"product_menu": {
+			"label": "Products",
+			"items": {
+				"catalog": { "label": "Catalog" },
+				"all_products": { "label": "Products" }
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/ui/data_views.json

@@ -0,0 +1,20 @@
+{
+	"product_grid": {
+		"label": "Products",
+		"description": "One grid, two column sets — whichever the folder's entity view allows",
+		"viewType": "grid",
+		"icon": "bi-box-seam",
+		"dataSources": [{
+			"entityCode": "product",
+			"columns": [
+				{ "column_cd": "name", "width": 240 },
+				{ "column_cd": "sku", "width": 120 },
+				{ "column_cd": "quantity", "width": 120 },
+				{ "column_cd": "cost_price", "width": 120 },
+				{ "column_cd": "sale_price", "width": 120 },
+				{ "column_cd": "margin", "width": 120 }
+			],
+			"order": ["name"]
+		}]
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/ui/folders.json

@@ -0,0 +1,23 @@
+{
+	"label": "Products",
+	"description": "Product master data",
+	"icon": "bi-box-seam",
+	"children": {
+		"warehouse": {
+			"label": "Warehouse",
+			"description": "Stock keeping — no pricing",
+			"color": "#0ea5e9",
+			"entities": {
+				"product": { "viewName": "storekeeper", "quickAdd": true }
+			}
+		},
+		"finance": {
+			"label": "Finance",
+			"description": "Costing and pricing",
+			"color": "#f59e0b",
+			"entities": {
+				"product": { "viewName": "accountant", "quickAdd": false }
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/ui/menus.json

@@ -0,0 +1,21 @@
+{
+	"product_menu": {
+		"label": "Products",
+		"items": {
+			"catalog": {
+				"orderNum": 1,
+				"label": "Catalog",
+				"icon": "box-seam",
+				"children": {
+					"all_products": {
+						"itemType": "V",
+						"label": "Products",
+						"icon": "box-seam",
+						"dataViewCode": "product_grid",
+						"orderNum": 1
+					}
+				}
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/simple-todo/manifest.json

@@ -6,10 +6,15 @@
 	"dbSchemaVersion": "0.0.1",
 	"displayName": "Simple Todo",
 	"description": "Minimal example module demonstrating the dForge package format",
-	"author": { "name": "dForge Examples" },
+	"author": {
+		"name": "dForge Examples"
+	},
 	"license": "MIT",
 	"category": "Examples",
-	"tags": ["example", "todo"],
+	"tags": [
+		"example",
+		"todo"
+	],
 	"icon": "bi-check-square",
 	"dependencies": {
 		"admin": ">=0.0.1"
@@ -19,14 +24,5 @@
 	"entities": {
 		"todo_list": "./entities/todo_list.json",
 		"todo_item": "./entities/todo_item.json"
-	},
-	"dataViews": "./ui/data_views.json",
-	"menus": "./ui/menus.json",
-	"actions": "./ui/actions.json",
-	"security": {
-		"roles": "./security/roles.json"
-	},
-	"seedData": [
-		"./seed-data/01-lists.json"
-	]
+	}
 }