@dforge-core/dforge-mcp 0.2.33 → 0.2.34

package/resources/schemas/settings.schema.json

@@ -10,7 +10,6 @@
 	"$defs": {
 		"setting": {
 			"type": "object",
-			"required": ["fieldTypeCd"],
 			"properties": {
 				"fieldTypeCd": {
 					"type": "string",
@@ -47,8 +46,32 @@
 				"params": {
 					"type": "object",
 					"description": "Field-type-specific parameters. Examples: dropdown → { options: [...] }; number → { min, max }; lookup → { link: { entity, otherKey } }."
+				},
+				"domain": {
+					"type": "string",
+					"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 fieldTypeCd, baseDatatypeCd and params; declaring any of those alongside 'domain' is rejected at install. The setting keeps its own label, defaultValue, formula and required flag."
 				}
 			},
+			"oneOf": [
+				{
+					"title": "Domain-backed setting",
+					"description": "Setting whose control and option list come from a reusable column domain. Requires 'domain' and must NOT restate what the domain owns.",
+					"required": ["domain"],
+					"properties": {
+						"fieldTypeCd": false,
+						"baseDatatypeCd": false,
+						"params": false
+					}
+				},
+				{
+					"title": "Inline setting",
+					"description": "Setting that declares its own control and parameters. Requires 'fieldTypeCd'.",
+					"required": ["fieldTypeCd"],
+					"properties": {
+						"domain": false
+					}
+				}
+			],
 			"additionalProperties": false
 		}
 	}

package/resources/schemas/traits.schema.json

@@ -79,9 +79,34 @@
 						"serverDefault": { "$ref": "#/$defs/serverDefault" }
 					},
 					"additionalProperties": true
+				},
+				"domain": {
+					"type": "string",
+					"description": "Reference to a reusable column domain. A bare 'domain_cd' resolves in the module of the entity taking the trait, then tenant-created domains, so one generic trait gives each module its own list; 'module_cd.domain_cd' pins one module's domain for every entity. A module's own traits.json must qualify a domain the module itself defines: written bare, it would bind to a same-named domain of whichever module takes the trait, and pack rejects it. The domain supplies the type, control, sizing and options."
 				}
 			},
-			"additionalProperties": false
+			"additionalProperties": false,
+			"oneOf": [
+				{
+					"title": "Domain-backed trait field",
+					"description": "Defers to a column domain. Must not restate what the domain owns, and takes no 'link' — it is a plain scalar column.",
+					"required": ["domain"],
+					"properties": {
+						"link": false,
+						"dbDatatype": false,
+						"fieldTypeCd": false,
+						"maxLen": false,
+						"params": false
+					}
+				},
+				{
+					"title": "Inline trait field",
+					"description": "Declares its own type and control, as trait fields always have.",
+					"properties": {
+						"domain": false
+					}
+				}
+			]
 		},
 		"serverDefault": {
 			"type": "object",

package/skills/dforge-mcp-author/references/conventions.md

@@ -42,8 +42,7 @@ my_module/
 │   ├── menus.json
 │   ├── actions.json
 │   ├── folders.json
-│   └── reports/
-│       └── <report>.json
+│   └── reports.json
 ├── security/
 │   └── roles.json
 ├── settings.json
@@ -54,6 +53,7 @@ my_module/
 │   └── de-DE.json              # IETF tags, one file per non-English locale
 ├── print_templates/
 │   └── <template>.scriban
+├── migrations/                  # upgrade data scripts, <version>.sql
 ├── files/                       # static assets
 └── webhooks.json                # optional
 ```
@@ -144,7 +144,8 @@ Both use **semver** (`MAJOR.MINOR.PATCH`).
 - If you added a new entity or column → bump both `version` and `dbSchemaVersion`.
 - If you changed a view or menu → bump `version` only.
 - If you changed translations only → bump `version` only.
-- The installer uses `dbSchemaVersion` to decide whether to run schema migrations. Wrong version = skipped migrations.
+- The installer uses `dbSchemaVersion` to decide whether to apply schema changes. Wrong version = skipped DDL.
+- Data a new version reshapes (backfill, move rows, drop a table it no longer declares) goes in `migrations/<version>.sql`, named by `version`, run once on an upgrade from below it. See `manifest.md` § Upgrade migrations.
 - **Never ship a package without bumping at least `version`** from the previous release. The installer may reject or silently skip a re-install with the same version.
 - For brand-new modules, start at `version: "0.1.0"` and `dbSchemaVersion: "0.0.1"`.
 

package/skills/dforge-mcp-author/references/manifest.md

@@ -111,7 +111,7 @@ Dependencies are a map of module codes to semver ranges. The installer checks th
 
 **Declare a dependency only on a module you actually consume something from** — an entity you reference with a link column, extend, grant rights on, or read in a view, report, formula or action. Every entry you write here obliges you to write a matching `deps/<module>.json` contract (below), so a speculative dependency is not free.
 
-**Do not depend on `admin`.** It — like `metadata` and `workspace` — is a system module, provisioned into every tenant before any other module installs. Depending on it buys nothing. The one legitimate reason to name a system module is to require a **minimum platform version** for a feature you use, e.g. `"metadata": ">=1.5.0"` for record-report attachments; that still needs a contract naming the entity the feature introduced.
+**Do not depend on `admin`.** It — like `metadata`, `workspace` and `sys-billing` — is a system module, provisioned into every tenant before any other module installs. Depending on it buys nothing. The one legitimate reason to name a system module is to require a **minimum platform version** for a feature you use, e.g. `"metadata": ">=1.5.0"` for record-report attachments. Its contract names the entity the feature introduced, or declares `"entities": {}` when the feature introduced none (`"admin": ">=1.21.0"` for upgrade migrations).
 
 **For bridge modules** (`crm-fin`, `wms-fin`, etc.), depend on both sides:
 
@@ -143,7 +143,7 @@ Every entry in `dependencies` needs a contract file at `deps/<module_code>.json`
 ```
 
 - `version` must be the same range as the manifest's dependency entry.
-- `entities` needs at least one entry; each needs a `pk` and a non-empty `use`.
+- `entities` needs at least one entry, except against a system module, where `{}` is a pure platform-version gate. Each entry needs a `pk` and a non-empty `use`.
 - `columns` is optional — omit it when you touch no specific column of that entity. Declare only real storage columns you read, write or join on, at their **storage class** (`int8`, `varchar`, `numeric`, `bool`, `date`, `timestamptz`, …; a `cuid` PK is `int8`). Never declare a virtual column (`R`/`S`/`F`) or a column your own extension adds.
 - `use` tokens are `<kind>:<symbol>` where kind is `ref`, `extends`, `formula`, `action`, `view`, `report`, `print` or `role`. `extends` must be fully qualified: `extends:parties.party`.
 
@@ -174,4 +174,22 @@ The extension file has `"extends": "fin.invoice"` inside. See MODULE_CONVENTIONS
 
 - Bump `version` on every release (bug fix, feature add, etc.).
 - Bump `dbSchemaVersion` **only** when the DB schema changes. If you added an action but no new columns, `version` goes up but `dbSchemaVersion` stays the same.
-- The installer uses `dbSchemaVersion` to decide whether to run migrations.
+- The installer uses `dbSchemaVersion` to decide whether to apply schema changes. Upgrade **data** scripts under `migrations/` are keyed by `version` instead — see below.
+
+## 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.

package/skills/dforge-mcp-author/references/reports.md

@@ -7,11 +7,14 @@ SP files: `logic/reports/rpt_*.sql`
 
 ## Structure
 
-A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), optional per-dataset `params`, and an optional `entities` array (record-report attachments). Panels reference datasets by code via `datasetCd`.
+A report has a `label`, a `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), optional per-dataset `params`, and an optional `entities` array (record-report attachments). Panels reference datasets by code via `datasetCd`.
+
+**Name it with `label`, describe it with `description`.** `label` is the report's name: page title, breadcrumb and parameter dialog. `description` says what it shows and appears under the label, as a data view's does. Without a `label` the description becomes the name, so a sentence ends up as the page title. `dforge_module_validate`, `module pack` and install warn about it; install does not refuse it. Translate the name as `reports.<cd>.label`.
 
 ```json
 {
     "sales_pipeline": {
+        "label": "Sales Pipeline",
         "description": "Open opportunities by stage",
         "datasets": {
             "pipeline": {
@@ -341,7 +344,8 @@ A report can be **attached to an entity** so it opens from a record — the way
 
 ```json
 "credit_check": {
-    "description": "Customer Credit Check — limit against outstanding AR and open quotes",
+    "label": "Credit Check",
+    "description": "Credit limit against outstanding AR and open quotes",
     "entities": [
         { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 },
         { "entityCd": "crm.quote",     "params": { "customer_id": "customer_id" }, "orderNum": 45 }

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

@@ -237,6 +237,10 @@ If none fire, skip specialized views for that entity.
 **3c. Reports** only when aggregation/grouping isn't covered by views — or when
 Phase 2a sent you here because the "action" only wanted to show a number.
 
+Give each report a short `label` (its name: page title, breadcrumb, parameter
+dialog) and a `description` of what it shows, which appears under the label.
+Without a label the description becomes the title, and validate/pack warn.
+
 Params are **report-scoped**: declare them in the report-level `parameters`
 block, or as shorthand under `datasets.<cd>.params` when exactly one dataset uses
 the param. The installer merges both into the report's one param set, report level

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

@@ -101,6 +101,11 @@ role / trigger / job counts. Then confirm both version strings with the user:
 - **`version`** — always bump (semver) before packing.
 - **`dbSchemaVersion`** — bump only if entity fields were added, removed, or
   type-changed since the last install.
+- **Data on upgrade** — if the new version moves or reshapes existing rows, or
+  removes an entity whose table must go, ship `migrations/<version>.sql` named by
+  the new `version` and declare `"admin": ">=1.21.0"`. The installer generates the
+  DDL; it never moves data or drops a table on its own. See
+  `dforge://docs/conventions` § Upgrade Migrations.
 
 Get explicit confirmation on both before packing. This version confirmation
 applies only to the initial pack. During the install-fix loop, re-pack without