@dforge-core/dforge-mcp 0.1.8 → 0.1.9

package/package.json

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