@dforge-core/dforge-mcp 0.2.16 → 0.2.18

package/CHANGELOG.md

@@ -4,6 +4,121 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.2.18
+
+Every counter a module updates — an on-hand quantity, a running balance, a used
+credit — was being written as a literal the script had read a statement earlier.
+Two callers read 10, both write 5, and one decrement is gone with nothing logged.
+`update()` has always accepted `{ inc: n }` for exactly this; nothing here said so,
+so nothing generated it.
+
+### Changed — `update()` documents relative values
+
+`update('wms.stock', [stock_id], { quantity: { inc: -params[qty] } })` adds `n` to
+the column's **current** value, computed by the database under the row lock the
+`UPDATE` already takes. The DSL reference gains a section under `update()` and the
+`dforge-mcp-author` action-DSL table gains the rule in the `update()` row: use it for
+every counter, balance and quantity — a literal is correct only for a value that does
+not depend on what is already stored.
+
+`inc` must be a number and the object's only key; `{ inrc: 5 }` throws rather than
+writing nothing. Not available for extension columns, whose row may not exist yet.
+
+Documentation only — `dforge_action_check` never parsed `update()` payloads, so
+`{ inc: n }` validated before this and still does.
+
+### Changed — `@dforge-core/metadata` → `0.0.22`, `resources/schemas/` re-vendored
+
+**A column code may no longer start with `_`.** `entity.schema.json`'s field pattern
+(and the per-view override pattern) tightened from `^[a-zA-Z_][a-zA-Z0-9_]*$` to
+`^[a-zA-Z][a-zA-Z0-9_]*$`, because the platform reserves the prefix: the record route
+reads `_`-prefixed query parameters as app state (`_layout`) rather than key columns,
+and the print-template context injects `_fmt`, `_raw`, `_color`, `_link`, `_today` and
+`_settings` alongside bare column names. **This can reject metadata that packed
+before** — rename the column; a leading underscore was never addressable end to end.
+
+**`constraints` is now a specified object instead of a bare `type: object`.** Each
+entry is `unique` (needs `fields`, and `expression` is refused — a unique constraint
+is its key columns) or `check` (needs `expression`; its optional `fields` does not
+build anything and is reported to the client as the fields to highlight, since an
+identifier inside a string literal is indistinguishable from a column name). `columns`
+survives as a **deprecated** alias for `fields` on a unique constraint — still built,
+still reported, warned about at install. `message` overrides the generated violation
+text and localizes under `entities.<entity>.constraints.<name>.message`. Editors now
+complete this and catch a `check` with no expression at authoring time.
+
+Two description corrections in the same bump: a **`reports.json` `entityCd` pointing
+outside the declaring module must be qualified `module.entity`** — `entity_cd` is
+unique per module, not per tenant, and the installer stores the id it resolves once,
+which `report.run` then reads for the life of the row; a bare code that several
+installed modules define is rejected at install unless one of them is this module or a
+declared dependency. And **an `extends` module cannot declare `views`** — a view lists
+the complete visible column set and an extension knows only the columns it adds — which
+`entity.schema.json` now says next to the rule (already shipped in 0.2.16) that a folder
+naming an undeclared view fails the install.
+
+Also arriving with `0.0.21`, platform-side and needing nothing from a module:
+`number`, `currency` and `percent` no longer ship `min`/`max` field-type defaults. The
+client merged those under a column's own `params` and validated the result, so every
+plain `number` column was silently capped at 10000 and refused negatives
+([dForge-core#947](https://github.com/iash44/dForge-core/issues/947)) — an odometer, a
+cargo weight, a negative variance. A numeric column is bounded only when its own
+`params` say so, which is unchanged and remains the way to state a real range.
+
+### Changed
+
+- `@dforge-core/dforge-cli` → `0.2.16`.
+
+Nothing else is rejected that was accepted before; apart from the `_`-prefixed column
+codes above, `dforge_module_validate` is unchanged.
+
+## 0.2.17
+
+A bridge module's `async: false` trigger **can** roll back its host module's write,
+and that is intended (platform issue #999). It is the same coupling a mandatory
+extension column already creates — mark one `M` and the host's own `data.insert`
+is refused with *"Missing required columns: …"* for a field the host knows nothing
+about. A bridge that can add a required field can add a required *condition*, and
+cross-module invariants are what bridge modules exist to enforce.
+
+What changed platform-side is that the veto now says who issued it, so the guidance
+here says what to point it at.
+
+### Changed — `async: false` is a refusal mechanism, not a reaction
+
+`dforge_trigger_add`'s `async` description and `dforge-module-build` Phase 2b both
+said only that a failure "rolls back the original change" — true, and read by an
+authoring agent as a footnote about transactions rather than as the decision it is.
+Both now state that the rollback reaches **another module's** entity, and the rule
+that follows: pick `async: false` to enforce an invariant, not merely to react,
+because a bug in the action blocks the host's workflow exactly as effectively as a
+real violation. Keep such an action to the check and put the rest behind
+`try`/`catch` or in an `async: true` trigger.
+
+### Changed — a blocked write names the module that blocked it
+
+Trigger failures now report error code **`TRIGGER_ACTION_FAIL`** (the other action
+phases keep `ACTION_EXECUTION_FAIL`), rendered as *Blocked by "crm-fin" (automation
+"on_invoice_posted"): Credit limit exceeded.* in the caller's locale, with the
+action's own `error()` text passed through. The module named is the one that
+**declared the trigger**, not the one owning the action — a bridge routinely
+subscribes its own trigger to an action living elsewhere, and what refused the write
+is the subscription. Nothing to change in a module for this; it is what an author
+should expect to see when their trigger fires.
+
+Nothing is rejected that was accepted before — `dforge_module_validate` is unchanged.
+
+### Changed
+
+- `@dforge-core/metadata` → `0.0.20`; `resources/schemas/` re-vendored. Besides
+  `triggers.schema.json`'s `async` above, that brings three description fixes from
+  platform work that landed alongside: `deps.schema.json` on how a target's `columns`
+  list treats a column your own `extends` file adds, `manifest.schema.json` warning
+  against sharing one `schema` between modules that extend other modules' entities
+  (extension columns live in `"{schema}"."{entity}_ext"`, which collides), and
+  `menus.schema.json` spelling out that `folders` takes flat folder codes
+  (`logistics_all_trips`), not paths.
+
 ## 0.2.16
 
 Entity views — the platform's **column-level security** — became reachable from a

package/dist/server.js

@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.14/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.16/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31214,7 +31214,7 @@ function buildZedSettings() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.18/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.22/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -31231,9 +31231,9 @@ var fieldTypes = [
   { cd: "phone", name: "Phone", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "url", name: "URL", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "textarea", name: "Multiline Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
-  { cd: "number", name: "Number", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false, defParams: { min: 0, max: 1e4 } },
-  { cd: "currency", name: "Currency", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: 2, useStringInFilter: false, defParams: { min: 0, max: 1e6 } },
-  { cd: "percent", name: "Percent", columnType: "D", baseDatatypeCd: "number", supportedAgg: "CAM", maxLen: null, precision: 2, useStringInFilter: false, defParams: { min: 0, max: 100 } },
+  { cd: "number", name: "Number", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "currency", name: "Currency", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: 2, useStringInFilter: false },
+  { cd: "percent", name: "Percent", columnType: "D", baseDatatypeCd: "number", supportedAgg: "CAM", maxLen: null, precision: 2, useStringInFilter: false },
   { cd: "checkbox", name: "Checkbox", columnType: "D", baseDatatypeCd: "bool", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
   { cd: "date", name: "Date", columnType: "D", baseDatatypeCd: "date", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
   { cd: "datetime", name: "Date & Time", columnType: "D", baseDatatypeCd: "timestamp", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
@@ -36248,7 +36248,7 @@ var triggerAddSchema = {
     "STATIC params only \u2014 the literal values given here. Nothing is injected at runtime; there is no record_id param. The affected record arrives as record context ([field]), its pre-change values as old[field]."
   ),
   async: external_exports.boolean().default(true).describe(
-    "When true (the platform default), the action runs in background \u2014 recommended for slow actions. When false, it runs in the caller's transaction, so a failing action ROLLS BACK the user's original write."
+    "When true (the platform default), the action runs in background \u2014 recommended for slow actions. When false, it runs in the caller's transaction, so a failing action ROLLS BACK the user's original write. That applies to a trigger on ANOTHER module's entity too: a bridge module CAN veto its host's write, the same way a mandatory extension column already refuses one. So async:false is a refusal mechanism \u2014 pick it to enforce an invariant, not merely to react, because a bug in the action blocks the host's workflow just as effectively as a real violation. The rollback is reported to the user as TRIGGER_ACTION_FAIL, naming the blocking module and trigger."
   )
 };
 function triggerAdd(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.16",
+	"version": "0.2.18",
 	"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.14",
-		"@dforge-core/metadata": "^0.0.18",
+		"@dforge-core/dforge-cli": "^0.2.16",
+		"@dforge-core/metadata": "^0.0.22",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/docs/dsl-reference.md

@@ -264,6 +264,20 @@ coerced to the PK storage type (snowflake-as-string binds `int8`). A null key
 update('comm.message', msg.message_id, { status: 'sent', sent_at: now() })
 ```
 
+**Relative changes — `{ inc: n }`.** A field value may be `{ inc: n }` instead of a
+literal, which adds `n` to the column's **current** value. Use it for every counter,
+balance or on-hand quantity:
+
+```dsl
+// The DATABASE subtracts, under the row lock the UPDATE already takes
+update('wms.stock', [stock_id], { quantity: { inc: -params[qty] } })
+```
+
+A literal can only carry a number the script read *before* the statement ran, so two
+callers that both read 10 both write 5 and one decrement is silently lost. `inc` must
+be a number and the object's only key — `{ inrc: 5 }` throws rather than writing
+nothing. Not available for extension columns (their row may not exist yet).
+
 #### `delete(entityCd, key) → int`
 Delete the row(s) matched by `key`; returns rows affected. Same key shapes and
 rules as `update()`.

package/resources/schemas/deps.schema.json

@@ -40,7 +40,7 @@
 				},
 				"columns": {
 					"type": "object",
-					"description": "Provider columns the consumer actually reads, writes, or joins on. Omit entirely for extension-only targets that touch no existing provider column.",
+					"description": "Provider columns the consumer actually reads, writes, or joins on. Omit entirely for extension-only targets that touch no existing provider column. A column your OWN 'extends' file adds to the provider needs no entry either — the platform exempts those and validates them separately — and a VIRTUAL extension field (columnType R/S/F: the lookup beside an FK, a reverse set, a formula) must never be listed at all: it is metadata, never a provider storage column, so no storage class can ever match and the install-time satisfaction check rejects the declaration. Declare the FK you add (e.g. trip_id), never the lookup beside it (trip).",
 					"additionalProperties": { "$ref": "#/definitions/columnContract" }
 				}
 			}

package/resources/schemas/entity.schema.json

@@ -49,9 +49,9 @@
 		},
 		"fields": {
 			"type": "object",
-			"description": "Column definitions keyed by column code. Column codes must start with a letter or underscore and contain only letters, digits, and underscores — a leading `-` is reserved for the sort descending prefix in `view_json.order`.",
+			"description": "Column definitions keyed by column code. Column codes must start with a LETTER and contain only letters, digits, and underscores. A leading `_` is reserved by the platform — the record route treats `_`-prefixed query parameters as app state (`_layout`) rather than key columns, and the print template context injects `_fmt`, `_raw`, `_color`, `_link`, `_today` and `_settings` alongside bare column names. A leading `-` is reserved for the sort descending prefix in `view_json.order`.",
 			"propertyNames": {
-				"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+				"pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
 			},
 			"additionalProperties": {
 				"$ref": "#/$defs/field"
@@ -59,7 +59,51 @@
 		},
 		"constraints": {
 			"type": "object",
-			"description": "Database constraints (unique, check, etc.)"
+			"description": "Database constraints, keyed by constraint name. Each becomes a real Postgres constraint; a violation is reported to the client under UNIQUE_VIOLATION or CHECK_VIOLATION with the constraint name, the owning entity and its declared fields.",
+			"additionalProperties": {
+				"type": "object",
+				"required": ["type"],
+				"allOf": [
+					{
+						"if": { "required": ["type"], "properties": { "type": { "const": "unique" } } },
+						"then": {
+							"anyOf": [{ "required": ["fields"] }, { "required": ["columns"] }],
+							"properties": { "expression": false }
+						}
+					},
+					{
+						"if": { "required": ["type"], "properties": { "type": { "const": "check" } } },
+						"then": { "required": ["expression"] }
+					}
+				],
+				"properties": {
+					"type": {
+						"type": "string",
+						"enum": ["unique", "check"],
+						"description": "Constraint kind"
+					},
+					"fields": {
+						"type": "array",
+						"items": { "type": "string" },
+						"description": "Columns the constraint governs. Required for 'unique' - it IS the key. Optional for 'check', where it does not build the constraint but is reported to the client as the fields to highlight - the expression is never parsed for this, because an identifier inside a string literal is indistinguishable from a column name."
+					},
+					"columns": {
+						"type": "array",
+						"items": { "type": "string" },
+						"deprecated": true,
+						"deprecationMessage": "Deprecated: use 'fields'. The constraint is still created and its violation still reports the columns - the alias is read as a fallback on a unique constraint - but 'fields' is the documented spelling, the only one a check constraint reads, and the only one that will keep working. Module install warns about this.",
+						"description": "DEPRECATED alias for 'fields' on a unique constraint - use 'fields' instead. Accepted when building the constraint and read as a fallback when reporting a violation."
+					},
+					"expression": {
+						"type": "string",
+						"description": "SQL boolean expression the row must satisfy. Required for 'check', and not valid on 'unique' - a unique constraint is defined by its key columns, not an expression."
+					},
+					"message": {
+						"type": "string",
+						"description": "Violation message shown to the user; overrides the generated default. Localizable via translations/<locale>.json under entities.<entity>.constraints.<name>.message"
+					}
+				}
+			}
 		},
 		"references": {
 			"type": "object",
@@ -98,7 +142,7 @@
 		},
 		"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.",
+			"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 show the entity's full column set; a folder naming a view that isn't declared here FAILS the install, since resolving it to nothing would show every column \u2014 the opposite of what naming a view asks for. A view can only be declared by the entity's own module: an extension ('extends') declaring 'views' is rejected, because a view lists the complete column set and an extension knows only the columns it adds.",
 			"propertyNames": {
 				"pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$",
 				"maxLength": 100
@@ -120,7 +164,7 @@
 					"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_]*$"
+						"pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
 					},
 					"additionalProperties": {
 						"$ref": "#/$defs/entityViewColumn"

package/resources/schemas/manifest.schema.json

@@ -49,7 +49,7 @@
 		},
 		"schemaName": {
 			"type": "string",
-			"description": "Database schema name override (defaults to module code, system modules use 'dForge')"
+			"description": "Database schema name override (defaults to module code, system modules use 'dForge'). Do NOT share one schema between modules that extend other modules' entities: an extension's columns live in \"{schemaName}\".\"{entity}_ext\", named for the schema rather than the module, and nothing records which module wrote a column — so install rejects a module that both shares its schema with another installed module and declares 'extends'. Leave unset (the module code, which is unique) for bridge modules."
 		},
 		"system": {
 			"type": "boolean",

package/resources/schemas/menus.schema.json

@@ -23,7 +23,7 @@
 				"folders": {
 					"type": "array",
 					"items": { "type": "string" },
-					"description": "Folder codes where this menu is available"
+					"description": "Flat folder codes this menu is linked to (module code for the root, module code + '_' + each nesting segment for children, e.g. 'logistics_all_trips'; the full path, the module-relative path, and a folder's own key when unique in the tree also resolve). Omit to link the menu to every folder the module declares. Scopes the folder-to-menu link only — every folder in ui/folders.json is created either way. A code matching no folder, or a key two branches share, fails the install."
 				},
 				"items": {
 					"type": "object",

package/resources/schemas/reports.schema.json

@@ -273,7 +273,7 @@
 			"properties": {
 				"entityCd": {
 					"type": "string",
-					"description": "Source entity code"
+					"description": "Source entity code. Qualify it as `module.entity` for anything outside the declaring module: entity_cd is unique per module, not per tenant, and the installer stores the id it resolves once — report.run reads that id for the life of the row. A bare code that several installed modules define is rejected at install unless one of them is this module or a declared dependency."
 				},
 				"columns": {
 					"type": "array",

package/resources/schemas/triggers.schema.json

@@ -50,7 +50,7 @@
 				"async": {
 					"type": "boolean",
 					"default": true,
-					"description": "When true (the default), 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 — so an async:false trigger can undo the user's write. Keep async:false actions fast; they run on the request's transaction."
+					"description": "When true (the default), 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 — so an async:false trigger can undo the user's write. That holds for a trigger on ANOTHER module's entity too (the bridge shape): a bridge can veto its host's write, the same way a mandatory extension column already refuses one. Use it to enforce an invariant, not merely to react — the error names the blocking module and trigger (code TRIGGER_ACTION_FAIL), and a bug in the action blocks the host's workflow just as effectively as a real violation. Keep async:false actions fast; they run on the request's transaction."
 				}
 			},
 			"additionalProperties": false

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

@@ -226,7 +226,7 @@ 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`. |
 | `select('entity', opts?)` | Array of row objects | Structured multi-row read — see "select()" below. `opts` = `{columns, filter, orderBy, limit, offset}`, all optional. Prefer over `query()` for row-shaped reads. |
-| `update('entity', key, { field: value, … })` | Rows affected (number) | Update the row(s) matched by `key`. Refreshes update-phase server defaults (audit `last_updated` / `last_updated_by`) and coerces values like `insert()`. |
+| `update('entity', key, { field: value, … })` | Rows affected (number) | Update the row(s) matched by `key`. Refreshes update-phase server defaults (audit `last_updated` / `last_updated_by`) and coerces values like `insert()`. A value may be `{ inc: n }` instead of a literal — adds `n` to the column's CURRENT value, so concurrent callers accumulate instead of overwriting. Use it for every counter / balance / quantity. |
 | `delete('entity', key)` | Rows affected (number) | Delete the row(s) matched by `key`. |
 | `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']`. **Escape hatch** — prefer `select()`/`update()`/`delete()` when the structured shape fits. |
 | `getRecord('entity', key)` | Row object | Fetch a single record by key. Access fields with `rec.field_name` (or `rec.get('field_name')`). **Throws** a localized "not found" error if absent. |

package/skills/dforge-module-build/SKILL.md

@@ -187,7 +187,13 @@ before committing, then `dforge_action_add`. One action per turn.
 
 **2b Triggers** reference actions that must already exist. `async: true` runs
 after the transaction commits (use for anything slow); `async: false` runs
-in-transaction, so a failure rolls back the original change.
+in-transaction, so a failure rolls back the original change — **including on
+another module's entity**. A bridge's `async: false` trigger vetoes its host's
+write, exactly as a mandatory extension column already refuses one, so pick it
+to enforce an invariant, not merely to react: a bug in the action blocks the
+host's workflow as effectively as a real violation. Keep such an action to the
+check itself and put everything else behind `try`/`catch` or in an
+`async: true` trigger.
 
 **2c Jobs** run as the system user with **no current record** — the action must
 not use `[field]` syntax. Wrap a record-context action in a thin job action that