@dforge-core/dforge-mcp 0.2.32 → 0.2.34

package/resources/schemas/translations.schema.json

@@ -32,9 +32,9 @@
 		},
 		"views": {
 			"type": "object",
-			"description": "Data view code → label.",
+			"description": "Data view code → label and description (the subtitle under the view title).",
 			"additionalProperties": {
-				"$ref": "#/$defs/labelOnly"
+				"$ref": "#/$defs/labelDesc"
 			}
 		},
 		"menus": {

package/skills/dforge-mcp-author/examples/column-security/README.md

@@ -60,8 +60,7 @@ correct: a data view describes the presentation, and the folder's entity view de
 what a user in that folder is allowed to see of it. The grid renders whichever
 columns survive the view — you do not maintain one data view per role.
 
-Entity views are also unrelated to the two other things called "view" here: a *data
-view* (`ui/data_views.json`) is a grid/kanban/calendar, and `isView` + `viewSql` on an
-entity means it is backed by a SQL view.
+Entity views are also unrelated to the other thing called "view" here: a *data view*
+(`ui/data_views.json`) is a grid/kanban/calendar.
 
 See `dforge://reference/security` → Column-level security for the full rules.

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/data-views.md

@@ -4,7 +4,7 @@ Data views define how users see and interact with entity data. One entity can ha
 
 Lives in: `ui/data_views.json`
 
-> **Not to be confused with entity views.** An *entity view* (`views` on an entity file) is column-level **security** — which columns a folder may see at all — and is what `folders.json`'s `viewName` binds. A *data view* is a presentation of an entity, referenced by a menu's `dataViewCode`. A third thing, `isView` + `viewSql` on an entity, means the entity is backed by a SQL view. See `security.md` → Column-level security.
+> **Not to be confused with entity views.** An *entity view* (`views` on an entity file) is column-level **security** — which columns a folder may see at all — and is what `folders.json`'s `viewName` binds. A *data view* is a presentation of an entity, referenced by a menu's `dataViewCode`. See `security.md` → Column-level security.
 
 ## Structure
 

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-mcp-author/references/security.md

@@ -318,16 +318,17 @@ Each of these is an install-time error, and each is silent at runtime if it slip
 
 `"viewName": "default"` means **no view** (full column set) and declares nothing. It is what every shipped module writes, and what the runtime auto-creates for an entity reached without a folder binding — so it is exempt from the checks above. A module that really declares a view named `default` still gets it bound.
 
-### Don't confuse the three "views"
+### Don't confuse the two "views"
 
 | Term | Where | What it is |
 |---|---|---|
 | **Entity view** | `entities/*.json` → `views` | Column-level security (this section) |
 | **Data view** | `ui/data_views.json` | A grid / kanban / calendar over an entity (`data-views.md`) |
-| **SQL view** | `entities/*.json` → `isView` + `viewSql` | An entity backed by a SQL view instead of a table |
 
 `viewName` in `folders.json` binds the first. Menus' `dataViewCode` references the second.
 
+There is no SQL-view entity. `isView` / `viewSql` are rejected at validate, pack and install: a view entity would duplicate the source entity's metadata, break when that module changes a column, and read around its row and column security. For a read-only slice use a data view (nav paths, `F` columns), a `G` total, the Query Builder, or a stored-procedure report — the last is the one way to show users a slice of an entity they have no rights on, behind an explicit `sp:` grant.
+
 ### When to use subfolders
 
 - **Multi-location modules** (warehouses, offices, branches) — one subfolder per location, filtered by location FK

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

@@ -38,7 +38,7 @@ Translation files mirror the module's content structure. Each translatable objec
         "crm.sales-rep": { "label": "Sales Representative" }
     },
     "views": {
-        "contacts": { "label": "Contacts" },
+        "contacts": { "label": "Contacts", "desc": "People associated with customers" },
         "contacts_list": { "label": "Contact List" },
         "contacts_gallery": { "label": "Contact Cards" }
     },
@@ -80,7 +80,7 @@ Translation files mirror the module's content structure. Each translatable objec
 | `entities` | Entity labels (`label`, `desc`) and all field labels | Entity codes → `{ label, desc, fields: { field_code: { label } } }` |
 | `folders` | Folder labels | Folder codes (root folder key from `ui/folders.json`) |
 | `roles` | Role display labels | Role codes (keys from `security/roles.json`, already module-qualified — e.g. `crm.admin`) → `{ label }` |
-| `views` | Data view labels | View codes (keys from `ui/data_views.json`) |
+| `views` | Data view labels and descriptions (`label`, `desc`) | View codes (keys from `ui/data_views.json`) → `{ label, desc }` |
 | `menus` | Menu node labels (root + nested items) | Menu root key → `{ label, items: { item_code: { label } } }` matching `ui/menus.json` structure |
 | `actions` | Action labels, descriptions, param labels **and param dropdown option labels** | Action codes (keys from `ui/actions.json`) → `{ label, desc, params: { param_cd: { label, options: { value: … } } } }` |
 | `reports` | Report dataset captions, param labels **and param dropdown option labels** | Report codes → `{ datasets: { ds_cd: { caption } }, params: { param_cd: { label, options: { value: … } } } }` |
@@ -242,7 +242,7 @@ If you include these sections, the install succeeds (they're silently ignored)
         "crm.sales-rep": { "label": "Vertriebsmitarbeiter" }
     },
     "views": {
-        "contacts": { "label": "Kontakte" }
+        "contacts": { "label": "Kontakte", "desc": "Personen, die mit Kunden verknüpft sind" }
     },
     "menus": {
         "crm_menu": {

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