@dforge-core/dforge-mcp 0.2.22 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.22",
+	"version": "0.2.24",
 	"description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/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",
@@ -35,8 +35,8 @@
 		"install-skills": "node scripts/install-skills.mjs"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.17",
-		"@dforge-core/metadata": "^0.0.22",
+		"@dforge-core/dforge-cli": "^0.2.19",
+		"@dforge-core/metadata": "^0.0.27",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/docs/dsl-reference.md

@@ -10,22 +10,25 @@ A `.dsl` file consists of four ordered, optional blocks (only `execute:` is requ
 
 ```dsl
 params:
-    # Parameter declarations (one per line)
+    // Parameter declarations (one per line)
 
 canExecute:
-    # Single-expression formula returning boolean
-    # Enables/disables the button AND is re-checked server-side on execute
-    # (see "canExecute is enforced, with a fail-open subset")
+    // Single-expression formula returning boolean
+    // 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)
+    // Pre-queue initialization (async / background actions only)
 
 execute:
-    # Main logic — required
+    // Main logic — required
 ```
 
 Block markers are case-insensitive but conventionally lowercase. Whitespace-indented bodies follow each marker. Blocks must appear in the order above when present.
 
+Comments are `//` and `/* … */`, as in JavaScript. **`#` is not a comment** — the
+compiler passes the line through and Jint rejects it as a syntax error at install.
+
 ---
 
 ## Execution modes
@@ -141,11 +144,11 @@ execute:
 - `old[fieldName]` — the field's value *before* the change, in an action invoked by an event trigger. Read-only; reads `null` on `insert` events and outside triggers
 
 ```dsl
-# Read
+// Read
 if ([quantity] > [available_qty]) { error("Not enough stock") }
 if ([supplier].[is_active] == false) { error("Supplier disabled") }
 
-# Write
+// Write
 [status] = 'closed'
 [closed_date] = now()
 ```
@@ -381,19 +384,19 @@ so ids stay exact through reads, writes and comparisons. Smaller `int8` values
 (counters, quantities) stay ordinary numbers, so arithmetic on them is unchanged.
 
 ```dsl
-[copy] = [owner_id]                            # exact round-trip
-[is_mine] = currentUserId() == [last_updated_by]   # exact — both sides BigInt
-[label] = '' + [owner_id]                      # "200650220910936067"
+[copy] = [owner_id]                            // exact round-trip
+[is_mine] = currentUserId() == [last_updated_by]   // exact — both sides BigInt
+[label] = '' + [owner_id]                      // "200650220910936067"
 ```
 
 Two operations throw instead of rounding silently:
 
 ```dsl
-[x] = [owner_id] + 1               # Cannot mix BigInt and other types
-[x] = Number([owner_id]) + 1       # explicit — and accepts the rounding
+[x] = [owner_id] + 1               // Cannot mix BigInt and other types
+[x] = Number([owner_id]) + 1       // explicit — and accepts the rounding
 
-[x] = JSON.stringify([owner_id])   # Do not know how to serialize a BigInt
-[payload] = { id: [owner_id] }     # assign the object; jsonb writes the number
+[x] = JSON.stringify([owner_id])   // Do not know how to serialize a BigInt
+[payload] = { id: [owner_id] }     // assign the object; jsonb writes the number
 ```
 
 Never write a large id as a bare numeric literal — the literal itself rounds
@@ -492,10 +495,10 @@ notify([approver_id], 'New purchase request from ' + [requester_name] + ' awaiti
 Two modes:
 
 ```dsl
-# Raw mode: (to, subject, body)
+// Raw mode: (to, subject, body)
 sendEmail('ap@acme.com', 'Bill ' + [bill_number] + ' approved', 'Amount: $' + [amount])
 
-# Template mode: (to, templateCd, dataObject) — template defined in module's email_templates/
+// Template mode: (to, templateCd, dataObject) — template defined in module's email_templates/
 sendEmail([customer_id].[email], 'order_confirmation', {
     orderNumber: [order_number],
     total: [total],
@@ -564,8 +567,8 @@ execute:
 Folder-scoped module setting — walks the folder inheritance chain up to the module default.
 
 ```dsl
-var prefix = getSetting('invoice_number_prefix')  # e.g. "INV-"
-var maxDays = getSetting('payment_due_days')      # e.g. 30
+var prefix = getSetting('invoice_number_prefix')  // e.g. "INV-"
+var maxDays = getSetting('payment_due_days')      // e.g. 30
 [due_date] = addDays(now(), maxDays)
 ```
 
@@ -666,7 +669,7 @@ An explicit `description` still wins.
 
 ```dsl
 var task = insert('workspace.task', { title: 'Follow up' })
-# Captioned by workspace.task's toString — no third argument needed.
+// Captioned by workspace.task's toString — no third argument needed.
 insert('workspace.task_note', { link: entityLink('workspace.task', task) })
 ```
 
@@ -674,14 +677,14 @@ insert('workspace.task_note', { link: entityLink('workspace.task', task) })
 Commit pending changes mid-script AND broadcast SSE updates to connected clients. **Async / background actions only** — in sync actions, everything commits at the end automatically.
 
 ```dsl
-# Long-running background job that wants to surface progress
+// Long-running background job that wants to surface progress
 execute:
     var total = records.count()
     var done = 0
     for rec in records {
         rec[processed_at] = now()
         done = done + 1
-        if (done % 100 == 0) { flush() }   # progress update every 100 records
+        if (done % 100 == 0) { flush() }   // progress update every 100 records
     }
 ```
 
@@ -788,7 +791,7 @@ execute:
 
 ```dsl
 execute:
-    var threshold = getSetting('high_value_threshold')   # e.g. 10000
+    var threshold = getSetting('high_value_threshold')   // e.g. 10000
     var ccApprover = getSetting('cc_approver_user_id')
     if ([amount] >= threshold && ccApprover != null) {
         notify(ccApprover, 'Large order requires your CC approval: $' + [amount])
@@ -928,15 +931,15 @@ execute:
 ### ❌ Using `[field]` in batch mode
 
 ```dsl
-# WRONG — batch mode has no "current record"
+// WRONG — batch mode has no "current record"
 execute:
     for rec in records {
-        [status] = 'closed'    # ← this references the dispatch context, not rec
+        [status] = 'closed'    // ← this references the dispatch context, not rec
     }
 ```
 
 ```dsl
-# RIGHT
+// RIGHT
 execute:
     for rec in records {
         rec[status] = 'closed'
@@ -948,13 +951,13 @@ execute:
 Jobs run as system user with no record context. The action must be entity-agnostic.
 
 ```dsl
-# WRONG — fails at runtime with "no record context"
+// WRONG — fails at runtime with "no record context"
 execute:
     if ([overdue_count] > 0) { notify([owner_id], 'Overdue') }
 ```
 
 ```dsl
-# RIGHT — fetch what you need via query
+// RIGHT — fetch what you need via query
 execute:
     var overdue = query('SELECT owner_id, COUNT(*) AS n FROM invoice WHERE due_date < CURRENT_DATE GROUP BY owner_id', {})
     for (var i = 0; i < overdue.length; i++) {
@@ -967,14 +970,14 @@ execute:
 The DSL body is not wrapped in an IIFE — `return` at top level is a parse error.
 
 ```dsl
-# WRONG
+// WRONG
 execute:
     if ([status] == 'closed') { return }
     [last_touched] = now()
 ```
 
 ```dsl
-# RIGHT — use exit() for early success, error() for early failure
+// RIGHT — use exit() for early success, error() for early failure
 execute:
     if ([status] == 'closed') { exit('Already closed', 'info') }
     [last_touched] = now()
@@ -988,9 +991,9 @@ execution path. The same script keeps the row on one path and discards it on
 another, and the difference isn't visible in the action.
 
 ```dsl
-# WRONG — is this insert kept or discarded? Depends on the path.
+// WRONG — is this insert kept or discarded? Depends on the path.
 execute:
-    insert('audit_log', { event: 'attempted_close', record_id: [id] })   # unreliable!
+    insert('audit_log', { event: 'attempted_close', record_id: [id] })   // unreliable!
     if ([balance_due] > 0) { error('Cannot close — balance owing') }
 ```
 
@@ -1003,7 +1006,7 @@ to be atomic — so don't design around it either way. Write the script so the
 question never arises: validate first.
 
 ```dsl
-# RIGHT — validate first, then perform side-effects
+// RIGHT — validate first, then perform side-effects
 execute:
     if ([balance_due] > 0) { error('Cannot close — balance owing') }
     insert('audit_log', { event: 'closed', record_id: [id] })
@@ -1015,17 +1018,17 @@ execute:
 The platform auto-generates the number on INSERT when the target column is empty. Manual `nextNumber()` + manual field-set risks double-allocating sequence values if you forget to leave the field blank.
 
 ```dsl
-# WRONG — wastes a sequence value
+// WRONG — wastes a sequence value
 execute:
     var n = nextNumber('purchase_order')
-    var po = insert('purchase_order', { po_number: n, ... })   # gets a DIFFERENT auto-number, n is wasted
+    var po = insert('purchase_order', { po_number: n, ... })   // gets a DIFFERENT auto-number, n is wasted
 ```
 
 ```dsl
-# RIGHT — let INSERT generate it
+// RIGHT — let INSERT generate it
 execute:
     var po = insert('purchase_order', { supplier_id: params[supplier].supplier_id })
-    info('Created PO ' + po.po_number)   # po_number was auto-populated
+    info('Created PO ' + po.po_number)   // po_number was auto-populated
 ```
 
 Only use `nextNumber()` explicitly when you need the number BEFORE insert (e.g. to mention in a notification or message).
@@ -1039,12 +1042,12 @@ Sync actions block the UI until they finish. A 30-second action freezes the user
 ### ❌ String-concatenating into SQL
 
 ```dsl
-# WRONG — injection-vulnerable + breaks on quotes
+// WRONG — injection-vulnerable + breaks on quotes
 var q = query('SELECT * FROM customer WHERE name = ' + "'" + params[name] + "'", {})
 ```
 
 ```dsl
-# RIGHT — use named placeholders
+// RIGHT — use named placeholders
 var q = query('SELECT * FROM customer WHERE name = @n', { n: params[name] })
 ```
 

package/resources/schemas/card-layouts.schema.json

@@ -0,0 +1,141 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Card Layouts",
+	"description": "Module-shipped card (form) layouts for a dForge module package (ui/card_layouts.json). Each key is the layout_name stored in dForge.entity_view_layout. Rows written from here carry module_id, so they are recreated on every install and removed on uninstall; a layout the tenant drew in the card editor has module_id NULL and is never touched.",
+	"type": "object",
+	"additionalProperties": {
+		"type": "object",
+		"properties": {
+			"entity": {
+				"type": "string",
+				"description": "Entity code the layout belongs to. Unqualified means this module owns the entity; the cross-module form 'module.entity' targets another module's entity (a bridge module shipping a layout for its host)."
+			},
+			"view": {
+				"type": "string",
+				"default": "default",
+				"description": "Entity view the layout hangs off, matching an entity_view row's view_name. Defaults to 'default' — the same fallback entity.getLayouts and entity.saveLayout use for an entity with no folder binding of its own. Matched against the entity's declared views case-insensitively, and filed under their spelling; the installer creates the view row only when nothing matches."
+			},
+			"isDefault": {
+				"type": "boolean",
+				"default": false,
+				"description": "Whether this layout opens by default. Honoured on FIRST install only, and only when the view has no default layout yet — once a tenant has chosen their own default, an upgrade does not take it back."
+			},
+			"description": {
+				"type": "string",
+				"description": "Human-readable note for the package author. Not stored."
+			},
+			"layout": {
+				"$ref": "#/$defs/cardLayout",
+				"description": "The layout body, stored verbatim into entity_view_layout.layout. Same shape the card editor saves."
+			}
+		},
+		"required": ["entity", "layout"],
+		"additionalProperties": false
+	},
+	"$defs": {
+		"cardLayout": {
+			"type": "object",
+			"properties": {
+				"sections": {
+					"type": "array",
+					"description": "Ordered sections rendered down the card.",
+					"items": { "$ref": "#/$defs/section" }
+				},
+				"sets": {
+					"type": "object",
+					"description": "Per-set-field view config, keyed by the set column code. Chooses the renderer a detail grid uses ('grid' or 'list') and its persisted options.",
+					"additionalProperties": {
+						"type": "object",
+						"properties": {
+							"viewType": {
+								"type": "string",
+								"enum": ["grid", "list"],
+								"description": "Set renderer. Defaults to the column's own metadata."
+							},
+							"options": {
+								"type": "object",
+								"description": "Opaque per-renderer options, passed verbatim to the set registration."
+							}
+						},
+						"additionalProperties": false
+					}
+				}
+			},
+			"required": ["sections"],
+			"additionalProperties": false
+		},
+		"section": {
+			"oneOf": [
+				{ "$ref": "#/$defs/columnGroupSection" },
+				{ "$ref": "#/$defs/setSection" },
+				{ "$ref": "#/$defs/tabGroupSection" }
+			]
+		},
+		"columnGroupSection": {
+			"type": "object",
+			"description": "A group of fields laid out in 1, 2 or 3 columns.",
+			"properties": {
+				"type": { "const": "columnGroup" },
+				"code": { "type": "string", "description": "Section code, unique within the layout." },
+				"label": { "type": "string", "description": "Section heading, in the module's authoring language. The installer gives it an entity_column_group row keyed on this section's code, so translations/<locale>.json localizes it under entities.<entity>.columnGroups.<code>.label and the card shows the localized heading." },
+				"cols": { "type": "integer", "minimum": 1, "maximum": 3, "description": "Field columns across the group. Defaults to the card's own setting." },
+				"columns": {
+					"type": "array",
+					"description": "Fields in the group, in render order. A bare string is the column code; the object form adds pixel sizing.",
+					"items": {
+						"oneOf": [
+							{ "type": "string" },
+							{
+								"type": "object",
+								"properties": {
+									"column_cd": { "type": "string", "description": "Column code on this entity." },
+									"width": { "type": "integer", "minimum": 1, "description": "Field width in px." },
+									"height": { "type": "integer", "minimum": 1, "description": "Field height in px — for multiline/textarea fields." }
+								},
+								"required": ["column_cd"],
+								"additionalProperties": false
+							}
+						]
+					}
+				}
+			},
+			"required": ["type", "code", "columns"],
+			"additionalProperties": false
+		},
+		"setSection": {
+			"type": "object",
+			"description": "An embedded detail grid for a 1:N set column — the master/detail building block. The label comes from the column's own metadata.",
+			"properties": {
+				"type": { "const": "set" },
+				"code": { "type": "string", "description": "Section code, unique within the layout." },
+				"setField": { "type": "string", "description": "Set column code on this entity (columnType 'S')." }
+			},
+			"required": ["type", "code", "setField"],
+			"additionalProperties": false
+		},
+		"tabGroupSection": {
+			"type": "object",
+			"description": "A tab bar whose tabs are other sections. This is how a record shows several detail grids without stacking them down one long form.",
+			"properties": {
+				"type": { "const": "tabGroup" },
+				"code": { "type": "string", "description": "Section code, unique within the layout." },
+				"tabs": {
+					"type": "array",
+					"minItems": 1,
+					"description": "Tabs in order. Each references a columnGroup section by its code, or a set column by its column code.",
+					"items": {
+						"type": "object",
+						"properties": {
+							"type": { "type": "string", "enum": ["section", "set"] },
+							"code": { "type": "string", "description": "The referenced section's code, or the set column's code." }
+						},
+						"required": ["type", "code"],
+						"additionalProperties": false
+					}
+				}
+			},
+			"required": ["type", "code", "tabs"],
+			"additionalProperties": false
+		}
+	}
+}

package/resources/schemas/data-views.schema.json

@@ -14,7 +14,7 @@
 			"properties": {
 				"viewType": {
 					"type": "string",
-					"enum": ["grid", "list", "kanban", "calendar", "gallery", "tree-grid", "diagram", "master-detail", "library", "matrix"],
+					"enum": ["grid", "list", "kanban", "calendar", "gallery", "tree-grid", "diagram", "library", "matrix"],
 					"default": "grid",
 					"description": "View display type. Optional — omitted or unknown values fall back to 'grid' at runtime."
 				},
@@ -57,7 +57,6 @@
 				{ "$ref": "#/$defs/rules/tree-grid" },
 				{ "$ref": "#/$defs/rules/list" },
 				{ "$ref": "#/$defs/rules/diagram" },
-				{ "$ref": "#/$defs/rules/master-detail" },
 				{ "$ref": "#/$defs/rules/matrix" }
 			]
 		},
@@ -118,17 +117,6 @@
 					}
 				}
 			},
-			"master-detail": {
-				"if": {
-					"properties": { "viewType": { "const": "master-detail" } },
-					"required": ["viewType"]
-				},
-				"then": {
-					"properties": {
-						"dataSources": { "minItems": 2 }
-					}
-				}
-			},
 			"matrix": {
 				"if": {
 					"properties": { "viewType": { "const": "matrix" } },
@@ -493,7 +481,7 @@
 				},
 				"label": {
 					"type": "string",
-					"description": "Human-readable label for this data source (used in master-detail tabs)"
+					"description": "Human-readable label for this data source"
 				},
 				"columns": {
 					"type": "array",

package/resources/schemas/entity.schema.json

@@ -38,6 +38,10 @@
 		"toString": {
 			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\". Optional in extension entities (with `extends`). No `type` constraint here because `toString` collides with Object.prototype.toString in JSON validators — they read the inherited function and reject it, even when the property is absent from the JSON."
 		},
+		"comments": {
+			"type": "boolean",
+			"description": "Records of this entity accept comments \u2014 the composer and thread appear on the record card, beside the audit history. Opt-in per entity; `comments` in the manifest sets a module-wide default that this overrides in both directions."
+		},
 		"traits": {
 			"type": "array",
 			"description": "Entity traits expanded during module install (authoring shortcut). Trait definitions loaded from DB (seeded by metadata module).",
@@ -221,9 +225,48 @@
 			},
 			"additionalProperties": false
 		},
+		"registryColumnParams": {
+			"type": "object",
+			"description": "params of an accumulation (A) or ledger (L) registry column. The lock lists are what BOTH generated guards freeze — the posted-document guard while the document is posted, the period guard while its period is closed — and they are required: install refuses a registry column that omits or empties them. The header's periodDateField and the state column are watched in addition, whatever the list says.",
+			"required": ["lockedFields"],
+			"properties": {
+				"lockedFields": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "type": "string", "minLength": 1 },
+					"description": "Header fields frozen while the document is posted and while its period is closed. Required. [\"*\"] freezes the whole row."
+				},
+				"lockedLineFields": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "type": "string", "minLength": 1 },
+					"description": "Line fields frozen under a posted or period-closed header. Required when lineEntity is declared, rejected when it is not. [\"*\"] freezes the whole row; the line's foreign key to the header is watched in addition."
+				},
+				"lineEntity": { "type": "string", "description": "The line entity, defined in this module. Declare together with lineField and lockedLineFields, or none of the three for a document without lines." },
+				"lineField": { "type": "string", "description": "The line's foreign-key column(s) to the header, comma-separated in the header's key order for a composite key." },
+				"stateField": { "type": "string", "description": "The bool column that records the posted state, when it is not the registry column itself. Written only by the register engine." },
+				"periodEntity": { "type": "string", "description": "Period entity this registry closes against — one of this module's, or 'module.entity' from a dependency." },
+				"periodDateField": { "type": "string", "description": "Header date column that resolves the period." },
+				"periodKeyField": { "type": "string", "default": "period_key" },
+				"periodClosedField": { "type": "string", "default": "closed" }
+			},
+			"dependencies": {
+				"lineEntity": ["lineField", "lockedLineFields"],
+				"lineField": ["lineEntity"],
+				"lockedLineFields": ["lineEntity"],
+				"periodEntity": ["periodDateField"]
+			},
+			"additionalProperties": true
+		},
 		"field": {
 			"type": "object",
 			"description": "Entity column/field definition",
+			"allOf": [
+				{
+					"if": { "required": ["columnType"], "properties": { "columnType": { "enum": ["A", "L"] } } },
+					"then": { "required": ["params"], "properties": { "params": { "$ref": "#/$defs/registryColumnParams" } } }
+				}
+			],
 			"properties": {
 				"dbDatatype": {
 					"type": "string",
@@ -551,8 +594,9 @@
 				"sign": { "$ref": "#/$defs/signConfig", "description": "Dynamic sign based on a field value (alternative to direction)" },
 				"autoCreateBalance": { "type": "boolean", "default": true },
 				"allowNegative": { "type": "boolean", "default": true },
-				"lockedFields": { "type": "array", "items": { "type": "string" }, "description": "Document fields locked when posted" }
+				"lockedFields": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Document fields locked when posted. Required; [\"*\"] freezes the whole row." }
 			},
+			"required": ["lockedFields"],
 			"additionalProperties": false
 		},
 		"signConfig": {

package/resources/schemas/jobs.schema.json

@@ -34,7 +34,7 @@
 					},
 					"params": {
 						"type": "object",
-						"description": "Static parameters passed to the action as __params. Folder-scoped overrides go through module settings, not here.",
+						"description": "Static parameters passed to the action as __params. Manifest-fixed — an admin cannot change them. For tenant-configurable values use module settings, which resolve from the job's bound folder (scheduled_job.folder_id, defaulting to the module root).",
 						"additionalProperties": true
 					},
 					"timeout": {
@@ -72,7 +72,7 @@
 					"paused": {
 						"type": "boolean",
 						"default": false,
-						"description": "Soft pause. Scheduler skips firing, but admin 'trigger now' still works."
+						"description": "Soft pause. Scheduler skips firing, but admin 'trigger now' still works. Seeds the initial value only — an upgrade never overwrites it, because an admin owns it at runtime."
 					}
 				},
 				"additionalProperties": false

package/resources/schemas/manifest.schema.json

@@ -107,6 +107,10 @@
 			"enum": ["none", "minimal", "full"],
 			"description": "Default audit history mode for entities in this module ('full' captures every field change; 'minimal' captures only inserts/deletes; 'none' disables). Individual entities can override."
 		},
+		"comments": {
+			"type": "boolean",
+			"description": "Default for `comments` on every entity in this module. Individual entities override it, including overriding true with false."
+		},
 		"entities": {
 			"type": "object",
 			"description": "Entity definitions and extensions: entity code → relative path to entity JSON file. Dotted keys (e.g. 'fin.invoice') indicate extensions of other modules' entities (the entity file must have an 'extends' property).",

package/skills/dforge-mcp-author/examples/matrix-budget/manifest.json

@@ -19,12 +19,5 @@
 	"entities": {
 		"budget_category": "./entities/budget_category.json",
 		"budget_line": "./entities/budget_line.json"
-	},
-	"dataViews": "./ui/data_views.json",
-	"security": {
-		"roles": "./security/roles.json"
-	},
-	"seedData": [
-		"./seed-data/01-categories.json"
-	]
+	}
 }