@dforge-core/dforge-mcp 0.2.17 → 0.2.18

package/CHANGELOG.md

@@ -4,6 +4,74 @@ 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,
@@ -40,6 +108,17 @@ 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.15/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.20/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 },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.17",
+	"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.15",
-		"@dforge-core/metadata": "^0.0.20",
+		"@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/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/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/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. |