@dforge-core/dforge-mcp 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.7",
+	"version": "0.1.9",
 	"description": "MCP server for dForge module authoring. Exposes scaffold/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
 	"license": "MIT",
 	"homepage": "https://github.com/iash44/dForge-core",
@@ -32,14 +32,14 @@
 	},
 	"dependencies": {
 		"@dforge-core/dforge-cli": "^0.2.7",
-		"@dforge-core/metadata": "^0.0.5",
+		"@dforge-core/metadata": "^0.0.8",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"zod": "^4.4.3"
 	},
 	"devDependencies": {
-		"@types/node": "^22.10.2",
+		"@types/node": "^22.20.1",
 		"tsup": "^8.5.1",
 		"typescript": "^6.0.3",
-		"vitest": "^3.2.0"
+		"vitest": "^3.2.7"
 	}
 }

package/resources/docs/dsl-reference.md

@@ -168,15 +168,28 @@ var po = insert('purchase_order', { supplier_id: params[supplier].supplier_id })
 insert('po_line', { po_id: po.purchase_order_id, product_id: [product_id], qty: 1 })
 ```
 
-#### `getRecord(entityCd, id) → record | null`
-Fetch a single record by PK. Returns null if not found.
+#### `getRecord(entityCd, key) → record`
+Fetch a single record by key. **Throws** a localized "not found" error if no row
+matches — the safe default for a lookup that should always resolve (e.g. an FK you
+just read). Fields are readable by dot notation (`rec.name`) or `rec.get('name')`.
+`key` is a scalar PK, or an object for a compound key: `getRecord('gl.tag', { tag_group: 'REGION', tag_code: 'EU' })`.
+The result is a **read-only** snapshot — writing to it (`rec.set(...)`) throws; use
+`update()` to persist. A null key value can't match, so it counts as not-found.
 
 ```dsl
 var rec = getRecord('crm.customer', [customer_id])
-if (rec == null) { error('Customer not found') }
 info('Customer: ' + rec.name + ' — credit limit $' + rec.credit_limit)
 ```
 
+#### `getRecordOrNull(entityCd, key) → record | null`
+Same as `getRecord`, but returns `null` instead of throwing when the row is absent —
+use it when a missing record is an expected outcome (optional lookup, upsert probe).
+
+```dsl
+var existing = getRecordOrNull('crm.customer', [customer_id])
+if (existing == null) { insert('crm.customer', { customer_id: [customer_id], name: [name] }) }
+```
+
 #### `callProc(name, args?) → record`
 Call a stored procedure with named args. Returns the proc's result row (or rows if it RETURNS TABLE).
 

package/resources/schemas/entity.schema.json

@@ -472,6 +472,16 @@
 						"field": { "type": "string" }
 					},
 					"additionalProperties": false
+				},
+				"onDelete": {
+					"type": "string",
+					"enum": ["cascade", "setNull", "restrict", "noAction"],
+					"description": "FK ON DELETE behaviour. Default (omitted) = noAction (plain FK). 'cascade' deletes children with the parent; 'setNull' nulls the FK column (must be nullable)."
+				},
+				"onUpdate": {
+					"type": "string",
+					"enum": ["cascade", "setNull", "restrict", "noAction"],
+					"description": "FK ON UPDATE behaviour. Default (omitted) = noAction. Fires when a parent's key value changes — a no-op for immutable cuid PKs, but useful for entities keyed on a natural/mutable PK."
 				}
 			},
 			"additionalProperties": false

package/resources/schemas/triggers.schema.json

@@ -50,7 +50,7 @@
 				"async": {
 					"type": "boolean",
 					"default": false,
-					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls). When false, the action runs in the same transaction; failures roll back the original DB change."
+					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller. Keep async:false actions fast — they run on the request's transaction."
 				}
 			},
 			"additionalProperties": false

package/skills/dforge-mcp-author/references/action-dsl.md

@@ -107,7 +107,8 @@ var note = params[note]             // no quotes around param name in this DSL
 |---|---|---|
 | `insert('entity', { field: value, … })` | Inserted row object | Insert a new record. Returns the full row including auto-filled columns (PK, audit, number sequences). Access returned fields with `result.field_name`. |
 | `query('SQL', { arg: value })` | Array of row objects | Execute parameterized SQL. Use `@argName` placeholders. Schema-qualified table names (`crm.contact`). Access row fields with `row.field_name` or `row['field_name']`. |
-| `getRecord('entity', id)` | Row object | Fetch a single record by primary key. |
+| `getRecord('entity', key)` | Row object | Fetch a single record by key (qualified `module.entity` supported). `key` is a scalar PK or an object for a compound key (`{ col_a: 1, col_b: 'x' }`). Access fields with `rec.field_name` (or `rec.get('field_name')`). **Throws** a localized "not found" error if absent. |
+| `getRecordOrNull('entity', key)` | Row object or `null` | Like `getRecord`, but returns `null` instead of throwing when the row is absent — use for an expected-absence lookup, guarded with `if (rec == null)`. |
 | `preloadRef('fk_column')` | Row object | Load the referenced record for a FK column. Access its fields with `ref.get('field')`. |
 
 ### Messaging

package/skills/dforge-mcp-author/references/data-views.md

@@ -58,6 +58,28 @@ Lives in: `ui/data_views.json`
 }
 ```
 
+## Critical rule — the entity needs a visible column
+
+A grid-style view can only render an entity that has at least one **visible scalar column** — a field whose `flags` include `V` and whose `columnType` is **not** a set (`S`). Column visibility is entity-driven (the field's flags), **not** view-driven: the `columns` array inside `dataSources[]` is layout-only (reorder/pin/width among already-visible fields) — it can't make a non-`V` field appear.
+
+If none of an entity's fields are visible (or only its set/child-collection columns are), the view renders the runtime empty state *"No visible columns configured for this entity."* — a broken screen the user only hits when they open the menu item. `dforge_module_validate` and `dforge_module_pack` now **reject** this before install.
+
+```jsonc
+// WRONG — grid over an entity whose fields are all hidden (no "V")
+"fields": {
+    "code": { "fieldTypeCd": "text", "flags": "EM" },   // E=editable, M=… but no V
+    "lines": { "columnType": "S", "flags": "VEM" }        // visible, but a SET — doesn't count for a grid
+}
+// RIGHT — at least one visible scalar field
+"fields": {
+    "code": { "fieldTypeCd": "text", "flags": "VEM" }     // V present, not a set → satisfies the grid
+}
+```
+
+This applies to every column-rendering view type (grid, list, kanban, calendar, gallery, tree-grid, master-detail, and the default). The column-agnostic types — `diagram`, `matrix`, `library` — draw from `viewConfig`/relationships instead, so they're **exempt** from this rule.
+
+See [flags.md](flags.md) for the flag string, [column-types.md](column-types.md) for `columnType` (`R`/`S`/`F`).
+
 ## View types
 
 | `viewType` | Description | `viewConfig` | When to use |
@@ -243,3 +265,4 @@ Most views only have one source. Order is view-level and applies to the primary
 - Object-array order like `[{ column_cd: "...", direction: "asc" }]` — **wrong shape for data views**. Use `string[]` with leading `-` for descending.
 - `viewType` is **optional** — omitted or unknown values fall back to `grid` at runtime. Set it explicitly for any non-grid view (`kanban`, `calendar`, `matrix`, …); a `matrix` view also **requires** a `viewConfig` with `rowAxis`/`colAxis`/`cell`.
 - Inventing view types like `"spreadsheet"` or `"table"` — **wrong**. Use `grid`.
+- A grid-style view over an entity with **no visible scalar column** (no field flagged `V`, or only set columns) — **rejected** at validate/pack. Mark at least one non-set field visible. See the [critical rule above](#critical-rule--the-entity-needs-a-visible-column). `diagram`/`matrix`/`library` are exempt.

package/skills/dforge-mcp-author/references/field-types.md

@@ -53,10 +53,12 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 
 ## Binary / file
 
-| `fieldTypeCd` | `baseDatatypeCd` | Description | Params |
-|---|---|---|---|
-| `file` | `binary` | Arbitrary file upload. | `accept`, `maxSize` |
-| `image` | `binary` | Image upload with preview. | `maxSize`, `dimensions` |
+> **Stored as `jsonb`, not `bytea`.** Despite the `binary` base datatype, a `file`/`image` column holds a JSON metadata reference (`{ storagePath, fileName, … }`) — the bytes live in file storage. The field tools derive `jsonb`; do **not** set `dbDatatype: "bytea"`.
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `file` | `binary` | Arbitrary file upload. | `jsonb` | `accept`, `maxSize` |
+| `image` | `binary` | Image upload with preview. | `jsonb` | `maxSize`, `dimensions` |
 
 ## Reference / lookup / set
 

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

@@ -72,6 +72,7 @@ For each entity:
 - [ ] Each source has `entityCode` and `columns`
 - [ ] `entityCode` points to an entity that exists
 - [ ] Column codes in `columns` all exist on the entity
+- [ ] The rendered entity has **at least one visible scalar column** (a field with `V` in `flags`, `columnType` not `S`) — a grid/list/kanban/etc. view over an entity whose fields are all hidden (or only sets) is **rejected** at validate/pack and would render "No visible columns configured for this entity." `diagram`/`matrix`/`library` are exempt
 - [ ] If set, `viewType` is from the supported list (`grid`, `list`, `kanban`, `calendar`, `gallery`, `tree-grid`, `diagram`, `master-detail`, `library`, `matrix`)
 - [ ] A `matrix` view has a `viewConfig` with `rowAxis`, `colAxis`, and `cell` (cell `entity` matches the primary `dataSources` entity; `rowKey`/`colKey` are real cell columns)
 - [ ] Sort uses the view-def-root `order` key — a `string[]` like `["-created_date", "name"]` (leading `-` = descending), NOT `sort` / `[{column_cd, direction}]` (that object shape belongs to queries & reports, not data views)
@@ -172,6 +173,7 @@ If you see any of these, stop and investigate:
 - Menus with `children: [...]` (array, not dict)
 - Roles with `entityRights` (wrong key)
 - Data views with root-level `entityCode` (should be inside `dataSources`)
+- A grid/list/kanban/etc. view over an entity with no field flagged `V` (or only set columns visible) — rejected at validate/pack
 - Formula columns without `baseDatatypeCd`
 - DSL actions with JavaScript/Python syntax
 - Seed data files without numbered prefixes