@dforge-core/dforge-mcp 0.2.32 → 0.2.34

package/package.json

@@ -1,49 +1,47 @@
 {
-	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.32",
-	"description": "MCP server for dForge module authoring. Exposes 35 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",
-	"packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
-	},
-	"bin": {
-		"dforge-mcp": "dist/server.js",
-		"dforge-install-skills": "scripts/install-skills.mjs"
-	},
-	"files": [
-		"dist/",
-		"docs/",
-		"resources/",
-		"skills/",
-		"scripts/install-skills.mjs",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"main": "dist/server.js",
-	"engines": {
-		"node": ">=18"
-	},
-	"scripts": {
-		"build": "tsup",
-		"sync-schemas": "node scripts/vendor-schemas.cjs",
-		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
-		"typecheck": "tsc --noEmit",
-		"test": "vitest run",
-		"install-skills": "node scripts/install-skills.mjs"
-	},
-	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.25",
-		"@dforge-core/metadata": "^0.0.32",
-		"@modelcontextprotocol/sdk": "^1.30.0",
-		"zod": "^4.4.3"
-	},
-	"devDependencies": {
-		"@types/node": "^26.2.0",
-		"tsup": "^8.5.1",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.10"
-	}
-}
+  "name": "@dforge-core/dforge-mcp",
+  "version": "0.2.34",
+  "description": "MCP server for dForge module authoring. Exposes 35 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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dforge-core/dforge-mcp.git"
+  },
+  "bin": {
+    "dforge-mcp": "dist/server.js",
+    "dforge-install-skills": "scripts/install-skills.mjs"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "resources/",
+    "skills/",
+    "scripts/install-skills.mjs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "main": "dist/server.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@dforge-core/dforge-cli": "^0.2.27",
+    "@dforge-core/metadata": "^0.0.34",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsup",
+    "sync-schemas": "node scripts/vendor-schemas.cjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "install-skills": "node scripts/install-skills.mjs"
+  }
+}

package/resources/docs/conventions.md

@@ -71,6 +71,8 @@ Use the CRM sample module (`modules/crm/`) as a reference implementation.
 ├── /print_templates/          # HTML/CSS print templates (optional)
 │   ├── invoice.html
 │   └── invoice.css
+├── /migrations/               # Upgrade data scripts, {version}.sql (optional)
+│   └── 0.2.0.sql
 └── /files/                    # Module static files (optional) — README, docs
     └── README.md
 ```
@@ -512,7 +514,7 @@ Two halves, both required:
 
 **`"default"` is the one exempt name** and means "no view" (full column set). It is what the ~100 shipped folder entries write, what `FolderExporter` writes back for a NULL `view_name`, and what the runtime auto-creates (column-less) for an entity reached without a folder binding — so rejecting it would fail every install. A module that really declares a view named `default` still gets it bound.
 
-Don't confuse the three things called "view": an **entity view** (`views`, this section) is column security; a **data view** (`ui/data_views.json`, referenced by a menu's `dataViewCode`) is a grid/kanban/calendar; `isView` + `viewSql` on an entity means it is backed by a SQL view. `folders.json`'s `viewName` binds the first.
+Don't confuse the two things called "view": an **entity view** (`views`, this section) is column security; a **data view** (`ui/data_views.json`, referenced by a menu's `dataViewCode`) is a grid/kanban/calendar. `folders.json`'s `viewName` binds the first. An entity is never backed by a SQL view — `isView` / `viewSql` are rejected; use a data view, a report or a stored procedure instead.
 
 ## Column Domains (`domains.json`)
 
@@ -964,6 +966,24 @@ Use semantic versioning: `MAJOR.MINOR.PATCH`
 1. **`version`**: Overall module version (includes all changes)
 2. **`dbSchemaVersion`**: Database schema version (only bumped for schema changes)
 
+### Upgrade Migrations (`migrations/`)
+
+A table or column change needs no script: the installer generates the DDL. A script is for the DATA a new version reshapes — filling a new column from an old one, moving rows to a new table, dropping a table the new version no longer declares (the platform never drops one on its own).
+
+```
+migrations/
+└── 0.11.0.sql      # runs on an upgrade from below 0.11.0 to 0.11.0 or later
+```
+
+- **Name** — the module `version` the file upgrades to, `MAJOR.MINOR.PATCH.sql`. Keyed by `version`, not `dbSchemaVersion`. A misnamed file, or one newer than the manifest `version`, fails the package at load.
+- **When** — on an upgrade only: every file above the installed version and no higher than the package's, in ascending order. A fresh install or a same-version reinstall runs none.
+- **Where** — inside the install transaction, after the new tables and columns exist and before `NOT NULL` is applied or a register's `totals` cache is rebuilt. A table the new version removed is still there to read. A failing script rolls the upgrade back and the module stays on the old version; refuse unconvertible data with `RAISE EXCEPTION '…'`, which the operator sees.
+- **Ids** — `"dForge".next_id()` mints a row id in SQL. Declare `"admin": ">=1.21.0"` in `dependencies`; that is also what guarantees a platform that runs migrations.
+- **Locks** — a script writing a posted document or its register journal wraps the writes in `SELECT set_config('registry.posting', 'true', true);` … `'false'`, so the post locks stand aside. Period locks do not; reopen a closed period and close it again.
+- A `kind: "pack"` module cannot carry migrations.
+
+Reference: `modules/gl/migrations/0.11.0.sql` in dForge-core.
+
 ---
 
 ## Installation & Reinstallation

package/resources/schemas/deps.schema.json

@@ -18,11 +18,16 @@
 		},
 		"entities": {
 			"type": "object",
-			"description": "Consumed provider entities, keyed by entity code (e.g. 'party').",
-			"minProperties": 1,
+			"description": "Consumed provider entities, keyed by entity code (e.g. 'party'). At least one, except against a system module (admin, metadata, workspace, sys-billing), where {} declares a pure platform-version gate for a feature that introduced no entity.",
 			"additionalProperties": { "$ref": "#/definitions/entityContract" }
 		}
 	},
+	"if": {
+		"not": { "properties": { "module": { "enum": ["admin", "metadata", "workspace", "sys-billing"] } }, "required": ["module"] }
+	},
+	"then": {
+		"properties": { "entities": { "minProperties": 1 } }
+	},
 	"definitions": {
 		"entityContract": {
 			"type": "object",

package/resources/schemas/domains.schema.json

@@ -2,7 +2,7 @@
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "https://dforge.dev/schemas/domains.schema.json",
 	"title": "dForge Column Domains",
-	"description": "domains.json — reusable, named semantic types. A domain bundles a base datatype, a control, sizing and a shared option list under one code; columns reference it via \"domain\": \"module_cd.domain_cd\" instead of restating the definition. Structural fields are materialized onto each column at install; options stay on the domain and resolve at metadata-load time, so a shared list is authored and translated exactly once.",
+	"description": "domains.json — reusable, named semantic types. A domain bundles a base datatype, a control, sizing and a shared option list under one code; columns reference it via \"domain\": \"domain_cd\" (this module's own) or \"module_cd.domain_cd\" (another module's) instead of restating the definition. Structural fields are materialized onto each column at install; options stay on the domain and resolve at metadata-load time, so a shared list is authored and translated exactly once.",
 	"type": "object",
 	"additionalProperties": {
 		"$ref": "#/$defs/domain"

package/resources/schemas/entity.schema.json

@@ -2,7 +2,7 @@
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "https://dforge.dev/schemas/entity.schema.json",
 	"title": "dForge Entity Definition",
-	"description": "Defines an entity (table/view mapping) for a dForge module",
+	"description": "Defines an entity (a table) for a dForge module",
 	"type": "object",
 	"anyOf": [
 		{ "required": ["fields"] },
@@ -24,16 +24,7 @@
 		},
 		"dbObject": {
 			"type": "string",
-			"description": "Database table or view name (defaults to entity code)"
-		},
-		"isView": {
-			"type": "boolean",
-			"description": "When true, entity maps to a SQL view (read-only, no DDL generation). Default: false (table-backed).",
-			"default": false
-		},
-		"viewSql": {
-			"type": "string",
-			"description": "SQL SELECT statement for view-backed entities (isView=true). Executed as CREATE OR REPLACE VIEW during module install."
+			"description": "Database table name (defaults to entity code)"
 		},
 		"toString": {
 			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\" — the caption of a record wherever it is referenced. Every `{placeholder}` must name a field of the entity (trait columns included) and not a set; pack and install fail otherwise. Omitted, the install generates one from the fields and warns. Not declared on 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."
@@ -151,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 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.",
+			"description": "Entity views keyed by view name — column-level security. Unrelated 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
@@ -250,12 +241,18 @@
 				"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." },
+				"register": { "type": "string", "description": "The register this column posts to, as 'module_cd.register_cd' (declared in that module's registers.json). Binding to one replaces restating what the register is: the declaration supplies the state entity, dimensions, resources, journal, allowNegative and autoCreate, and this column keeps only what legitimately differs per writer — direction/sign, 'map' and 'dateField'." },
+				"map": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this document's column carrying it. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines)." },
+				"headerMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this DOCUMENT's column carrying it, for a binding that posts from LINES. A line binding reads every other value off the line, and a dimension that belongs to the document (a dealer, an organisation, a date) cannot be put on the line: a G column is a same-row expression or an aggregate over a child set, so it cannot read a parent. Explicit rather than a fallback, because 'not on the line, try the header' turns a typo into a silent read of an unrelated header column with the same name. Install refuses: a name on neither table, a field also named in 'map', a column also read off the line by 'map', a column that is part of the line's key, a column 'lockedFields' does not freeze (the posting is keyed by it, so it has to hold still while the document is posted), and a RESOURCE unless the register is 'info' (a quantity from the document would be added once per line; an information register's records replace rather than add). A value may be a one-hop reference path off the document, whose reference key column 'lockedFields' must then freeze." },
+				"dateField": { "type": "string", "description": "This document's date column, supplying the date the register stamps on each journal row. Required once the register declares a 'journalDate' — one writer that supplied none would make every balance read as of a date quietly short, across all writers. On an accumulation (A) column it may be a one-hop reference path, '<reference column>.<target column>'." },
+				"skipPostingWhenEmpty": { "type": "array", "items": { "type": "string" }, "description": "THE EXCEPTION, not the normal way to model this — read the guide before declaring it. Register dimensions (by the register's names) whose empty value means THIS POSTING records nothing: the line, or the document when the binding posts from the document. One posting is skipped, never the register and never the document. When that is all the document would have recorded it is left unposted to this register, and the flag is per binding, so its other registers post as usual. An empty dimension NOT listed refuses the posting, naming the row and the dimension. It leaves a document fully posted while some of its lines produced no movement, which usually means the document is modelling two kinds of line in one table: since 'lineEntity' is declared per BINDING, prefer giving each register its own line table (goods lines post to stock, service lines do not) so that every line of each table posts. Declare this only when the distinction is not structural but lives in the data — a batch or serial number filled on some rows and not others — so there is no second table to put those rows in. Accumulation (A) columns only. Formerly skipWhenNull: a package using the old name is refused at install, while a tenant's already-stored params keep being read under it." },
 				"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": {
+				"headerMap": ["lineEntity"],
 				"lineEntity": ["lineField", "lockedLineFields"],
 				"lineField": ["lineEntity"],
 				"lockedLineFields": ["lineEntity"],
@@ -398,7 +395,7 @@
 				},
 				"domain": {
 					"type": "string",
-					"description": "Reference to a reusable column domain, qualified as 'module_cd.domain_cd' (unqualified resolves within this module, then tenant-created domains). The domain supplies dbDatatype, baseDatatypeCd, fieldTypeCd, maxLen, precision and params; declaring any of those alongside 'domain' is rejected at install. The column keeps its own description, flags, orderNum, isNullable and isPk."
+					"description": "Reference to a reusable column domain. A bare 'domain_cd' means this module's own domain, then a tenant-created one, and never another module's, even one with the same code. 'module_cd.domain_cd' names a domain of any installed module; declare that module as a dependency. The domain supplies dbDatatype, baseDatatypeCd, fieldTypeCd, maxLen, precision and params; declaring any of those alongside 'domain' is rejected at install. The column keeps its own description, flags, orderNum, isNullable and isPk."
 				},
 				"refFilter": {
 					"description": "Filter criteria for reference lookups. Condition values support @[field] placeholders resolved against the current record at lookup time (e.g. {\"c\":\"channel\",\"o\":\"eq\",\"v\":\"@[channel]\"} narrows options to rows matching the record's own channel), and @[ref].[field] nav placeholders that read through a Reference column, as a formula does (e.g. @[purchase_order].[supplier_id] on an order line narrows to the order's supplier, also in the New dialog of the order's Lines set). A condition whose placeholder is unset is dropped rather than matching nothing."