@dforge-core/dforge-mcp 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.8",
+	"version": "0.1.10",
 	"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/SKILL.md

@@ -110,7 +110,7 @@ Always-on cheat-sheet — enough to author inline; load the linked `references/*
 - **Flags** = letters from `V I E M H` only (no `U`/`S`/`P`): `VEM` required+visible, `VE` optional+visible, `V` read-only, `EM` hidden FK, `I` trait-provided. → `flags.md`
 - **Field types:** `fieldTypeCd` = UI control, `dbDatatype` = SQL type. **Omit `dbDatatype` on plain data columns — it's derived from `fieldTypeCd`** (`currency` → `numeric(18,2)`, `text` → `varchar`). Only set it for a **hidden FK** (no `fieldTypeCd`, so use the target PK type `cuid`) or to override size/precision. When you do set it: never the same as `fieldTypeCd`, and never `"number"` (use `int`/`bigint`/`numeric`). Common `fieldTypeCd` fixes: `number` not `integer`/`float`, `phone` not `phoneNumber`, `date` not `datePicker`. Common `dbDatatype` fixes: `timestamptz` not `datetime`/`timestamp`, `bool` not `boolean`, `varchar`/`text` not `string`. (Invalid `fieldTypeCd`/`columnType` are now rejected at authoring time.) → `field-types.md`
 - **Formula columns** (`columnType: "F"`): `baseDatatypeCd` required, no `dbDatatype`, `flags: "V"`. → `formulas.md`
-- **Roll-up totals** over a child set → Formula `F` with `SUM([set].[field])` (query-time). Never a Generated `G` column aggregating a virtual `F`/`R`/`S` child — its DB trigger reads `OLD.<field>` and install fails (`column old.<field> does not exist`). → `column-types.md`
+- **Roll-up totals** over a child set → Generated `G` column with `SUM([set].[field])` (`dbDatatype` + `formula`, no `link`/`baseDatatypeCd`); the installer maintains it with a DB trigger. **Not** a Formula `F` — an `F` set-aggregate is unsupported and silently renders empty. Aggregate only a **physical** child column (`D` or same-row `G`); a virtual `F`/`R`/`S` child fails install (`column old.<field> does not exist`). → `column-types.md`
 - **Column defaults:** entity *data* columns have **no** `defaultValue`/`default` key. Set a default via a formula (`"formula": "TODAY()"`, `"formula": "'draft'"`) or in action/trigger logic. `defaultValue` is **settings-only**. → `field-types.md`
 - **Traits:** default `["identity", "audit"]`; `audit-full` (when the user needs *who*-tracking) adds required `created_by`/`last_updated_by` with no default — if such an entity is **seeded**, set both to the System user `0` in every record, or don't seed it. → `traits.md`
 - **`toString`:** every entity needs one, `{column}` braces, e.g. `"{first_name} {last_name}"`.
@@ -209,7 +209,7 @@ Push back on verb-less answers ("admins and users" → "What does an admin do th
 2. Every action's `canExecute` guard references a status value that exists in that entity's options list.
 3. Every seed record's FK references a parent entity that also has seed data (referential integrity in load order).
 4. Every formula column uses only fields that exist on the same entity or a directly referenced entity (exactly 1 FK hop). Transitive references (2+ hops) are async and must have been flagged in the Phase 0c gap scan.
-5. Any `SUM([set].[field])` formula is flagged as version-dependent.
+5. Any set aggregate (`SUM`/`COUNT`/`AVG`/`MIN`/`MAX` over `[set].[field]`) is a Generated (`G`) column — never a Formula (`F`) column (an `F` set-aggregate silently renders empty) — and aggregates only a **physical** child column (`D` or same-row `G`), never a virtual `F`/`R`/`S` child.
 6. Every seeded entity handles audit traits: if it uses `audit-full`, every seed record sets `created_by`/`last_updated_by` to the System user `0` (else use `audit` / don't seed it) — `audit-full`'s required user columns otherwise fail seed install.
 
 Once all checks pass, present a brief summary (entity count, action count) and ask for final confirmation before calling `dforge_module_create`.
@@ -380,7 +380,7 @@ Load `dforge://reference/validation-checklist`. Run through **every section** in
 **Top install-blockers — scan these first** (each is a documented real install failure the platform validator rejects):
 
 1. **DSL dates:** `execute:` blocks use lowercase `now()`; never `TODAY()`/`NOW()` (formula-only → `'TODAY' is not defined`).
-2. **Roll-ups:** a total over a child set is a Formula (`F`) column with `SUM([set].[field])` — never a Generated (`G`) column aggregating a virtual `F`/`R`/`S` child (→ `db_error: column old.<field> does not exist`).
+2. **Roll-ups:** a total over a child set is a Generated (`G`) column with `SUM([set].[field])` (`dbDatatype` + `formula`) — never a Formula (`F`) column (an `F` set-aggregate silently renders empty). Aggregate only a **physical** child column (`D` or same-row `G`); a virtual `F`/`R`/`S` child fails install (→ `db_error: column old.<field> does not exist`).
 3. **Rights keys:** actions/reports/folders use a **colon** (`action:x`, `report:x`, `folder:x`); entities are bare or cross-module-dotted; deny by omitting the key, never `""`.
 4. **Manifest:** no `translations` key (translation files auto-discovered; non-English locales → `supportedLocales`).
 5. **Column defaults:** set via `formula` / `numberSequence` / DSL — never a `defaultValue` key on an entity field.

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/column-types.md

@@ -10,9 +10,9 @@ Every column has a `columnType` (optional for the default physical type). Seven
 | `"F"` | No | **Formula column** — virtual computed value. Evaluated by the formula engine. |
 | `"A"` | Yes | **Accumulation register column** — stores posted state for accumulation registers. Advanced (accounting modules). |
 | `"L"` | Yes | **Ledger register column** — stores posted state for double-entry bookkeeping. Advanced (accounting modules). |
-| `"G"` | Yes | **Generated column** — DB-level computed aggregate (e.g. SUM over child set via trigger, or PostgreSQL `GENERATED ALWAYS AS`). The aggregated child column **must be physical** (a `D` column) — never a virtual `F`/`R`/`S` column. For a simple roll-up total, prefer `F` (see below). |
+| `"G"` | Yes | **Generated column** — DB-level computed value. Two strategies, auto-detected from the formula: a **trigger-based aggregate over a child set** (`SUM([lines].[amount])`), or a same-row PostgreSQL `GENERATED ALWAYS AS` (`[qty] * [price]`). This is the correct type for **roll-up totals over child rows** (see below). The aggregated child column **must be physical** (a `D` column, or a same-row `G`) — never a virtual `F`/`R`/`S` column. |
 
-**For most module development, you'll only use D, R, S, and F.** Types A, L, and G are for advanced accounting/registry modules that use the `postable`, `accumulation`, or `ledger` traits.
+**For most module development, you'll use D, R, S, and F.** Add `G` when you need a **roll-up total over a child set** (`SUM`/`COUNT`/`AVG`/`MIN`/`MAX`) — see below. Types A and L are for advanced accounting/registry modules that use the `postable`, `accumulation`, or `ledger` traits.
 
 ## Data columns (`columnType` omitted or `"D"`)
 
@@ -147,33 +147,43 @@ Do **not** include `dbDatatype` on formula columns (there's no physical storage)
 
 See `formulas.md` for syntax.
 
-## Roll-up totals over child rows — use `F`, not `G`
+## Roll-up totals over child rows — use `G`, not `F`
 
 To total a child set on a header (line items → order total, movements → quantity on hand),
-**use a Formula column (`"F"`) with `SUM([set].[field])`**. It is computed at query time, so it
-can reference **any** child column — including the child's own formula columns.
+**use a Generated column (`"G"`) with `SUM([set].[field])`**. The installer detects the set
+navigation and generates a database trigger on the child table that keeps the parent value current
+on every child insert/update/delete. Because the value is **physically stored**, it displays
+everywhere (grid, form, reports) and is **filterable and sortable** in queries.
 
 ```json
-// purchase_order.total_amount — query-time roll-up (installs cleanly)
+// purchase_order.total_amount — trigger-maintained roll-up
 "total_amount": {
-    "columnType": "F",
-    "fieldTypeCd": "currency",
-    "baseDatatypeCd": "number",
+    "columnType": "G",
+    "dbDatatype": "numeric(18,2)",
+    "formula": "SUM([lines].[amount])",
     "flags": "V",
     "orderNum": 90,
-    "formula": "SUM([lines].[line_total])",      // line_total may itself be a formula column
     "description": "Total Amount"
 }
 ```
 
-> ⛔ **Never make a `G` (Generated) column aggregate a virtual `F` column.** A `G` aggregate is
-> maintained by a database trigger that reads the child's `OLD`/`NEW` *physical* values. A formula
-> (`F`) column has no physical storage, so the trigger references a column that doesn't exist and
-> **install fails** with `db_error: column old.<field> does not exist`. If you need a stored
-> (`G`) aggregate over a *derived* quantity (e.g. a signed movement quantity), make that child
-> column **physical** first — either a plain `D` column written by the action logic, or a
-> same-row `G`/`GENERATED ALWAYS AS` column with a `dbDatatype` — then aggregate that. For most
-> modules a query-time `F` roll-up is the right choice; reserve `G` for high-volume stored aggregates.
+A `"G"` roll-up requires `dbDatatype` and `formula`; it must **not** have `link` or
+`baseDatatypeCd`. Supported aggregate functions: `SUM`, `COUNT`, `AVG`, `MIN`, `MAX` (`SUM`/`COUNT`
+default to `0` when there are no children; `MIN`/`MAX`/`AVG` return `NULL`). All set references
+inside one aggregate must point at the **same** set column, and `COUNT(*)` is rejected — write
+`COUNT([lines])`.
+
+> ⛔ **Do not use a Formula (`F`) column for set aggregation.** `SUM([set].[field])` in an `F`
+> column is **not supported** by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and
+> nav resolution only walks single-hop N:1 references, never a 1:N set. The column silently renders
+> **empty** on the form, grid, and reports (no error). `F` is for same-row expressions
+> (`[qty] * [price]`) and single-hop reference navigation (`[account].[name]`) only.
+
+> ⛔ **The aggregated child column must be physical.** A `G` trigger reads the child's `OLD`/`NEW`
+> physical values, so aggregating a **virtual** child column (`F`/`R`/`S`) fails at install with
+> `db_error: column old.<field> does not exist`. To roll up a *derived* quantity (e.g. a signed
+> movement amount), make that child column physical first — a plain `D` column written by action
+> logic, or a same-row `G`/`GENERATED ALWAYS AS` column with a `dbDatatype` — then aggregate that.
 
 ## Quick reference: which columnType do I use?
 
@@ -183,6 +193,6 @@ can reference **any** child column — including the child's own formula columns
 - **"Compute full_name from first_name + last_name"** → `"F"`
 - **"User picker" (points to admin.user)** → omit `columnType`, use `fieldTypeCd: "user"` (writes user ID directly, no paired FK)
 - **"Polymorphic link to any entity"** → omit `columnType`, use `fieldTypeCd: "entitylink"` (stored as JSON)
-- **"Roll-up total over child rows"** (line items → header total, movements → quantity on hand) → `"F"` with `SUM([set].[field])` (query-time; see "Roll-up totals" above). Reserve `"G"` for high-volume *stored* aggregates, and only over a **physical** child column — never over an `F` column.
+- **"Roll-up total over child rows"** (line items → header total, movements → quantity on hand) → `"G"` with `SUM([set].[field])` (trigger-maintained, stored; see "Roll-up totals" above). Aggregate only a **physical** child column — never an `F`/`R`/`S` column. Do **not** use `"F"` for set aggregation — it silently renders empty.
 - **"Accumulation register state"** → `"A"` (advanced accounting — requires `postable` + `accumulation` traits)
 - **"Double-entry ledger state"** → `"L"` (advanced accounting — requires `postable` + `ledger` traits)

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/formulas.md

@@ -83,19 +83,32 @@ FORMAT([created_date], "yyyy-MM-dd")
 - `NULLIF(a, b)` — null if equal, else a
 - `ISNULL(x)` — boolean null check
 
-### Aggregation (on set columns)
+### Aggregation over a child set — use a Generated (`G`) column, not `F`
 
-- `COUNT([set_column])` — count related rows
-- `SUM([set_column].[field])` — sum a child field over a set
+- `SUM([set].[field])` — sum a child field over a set
+- `COUNT([set])` — count related rows (`COUNT(*)` is rejected)
 - `AVG`, `MIN`, `MAX` similarly
 
-Put set aggregations in a **Formula (`F`) column** — they evaluate at query time and may reference
-any child column, including the child's own formula columns, e.g. `SUM([lines].[line_total])`.
+> ⚠️ **Set aggregation is NOT a Formula (`F`) feature.** `SUM([set].[field])` in an `F` column is
+> unsupported by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and nav resolution
+> only walks single-hop N:1 references, never a 1:N set. It silently renders **empty** (no error).
 
-> ⛔ Do **not** put a `SUM([set].[field])` in a **Generated (`G`)** column unless `field` is a
-> *physical* (`D`) column. A `G` aggregate is maintained by a DB trigger that reads the child's
-> `OLD`/`NEW` physical values; aggregating a virtual `F` child fails at install with
-> `db_error: column old.<field> does not exist`. See `column-types.md` → "Roll-up totals over child rows".
+Put set aggregations in a **Generated (`G`) column** instead. The installer detects the set
+navigation and maintains the value with a database trigger on the child table. The aggregated
+child column must be **physical** (a `D` column, or a same-row `G`) — never a virtual `F`/`R`/`S`
+column, which fails at install with `db_error: column old.<field> does not exist`. Full details
+and the JSON shape: `column-types.md` → "Roll-up totals over child rows — use `G`, not `F`".
+
+```json
+"total_amount": {
+    "columnType": "G",
+    "dbDatatype": "numeric(18,2)",
+    "formula": "SUM([lines].[amount])",
+    "flags": "V",
+    "orderNum": 90,
+    "description": "Total Amount"
+}
+```
 
 ## Navigation (dot notation)
 

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

@@ -7,7 +7,7 @@ Run through this checklist **before** declaring a module complete. Always start
 These five have each caused a real install failure. Check them before the section-by-section pass:
 
 - [ ] **DSL dates** — `execute:` blocks use lowercase `now()`, never `TODAY()`/`NOW()` (formula-only; otherwise install fails `'TODAY' is not defined`)
-- [ ] **Roll-up totals** — a sum over a child set is a Formula (`F`) column with `SUM([set].[field])`, **not** a Generated (`G`) column over a virtual `F`/`R`/`S` child (otherwise `db_error: column old.<field> does not exist`)
+- [ ] **Roll-up totals** — a sum over a child set is a Generated (`G`) column with `SUM([set].[field])` (`dbDatatype` + `formula`, no `link`/`baseDatatypeCd`), **not** a Formula (`F`) column (an `F` set-aggregate silently renders empty). The aggregated child column must be physical (`D` or same-row `G`) — never a virtual `F`/`R`/`S` child (otherwise `db_error: column old.<field> does not exist`)
 - [ ] **Rights keys** — actions/reports/folders use a **colon** (`action:x`, `report:x`, `folder:x`); entities bare or cross-module-dotted; deny by omitting the key, never `""`
 - [ ] **Manifest** — no `translations` key (auto-discovered; non-English locales go in `supportedLocales`)
 - [ ] **Column defaults** — set via `formula` / `numberSequence` / DSL, never a `defaultValue` key on an entity field