@dforge-core/dforge-mcp 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.5",
+	"version": "0.1.7",
 	"description": "MCP server for dForge module authoring. Exposes scaffold/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",
@@ -31,7 +31,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.2",
+		"@dforge-core/dforge-cli": "^0.2.7",
 		"@dforge-core/metadata": "^0.0.5",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"zod": "^4.4.3"

package/resources/docs/conventions.md

@@ -581,6 +581,11 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 				"department_id": { "label": "Department ID" },
 				"department_name": { "label": "Department Name" }
 			}
+		},
+		"employee": {
+			"constraints": {
+				"chk_salary_positive": { "message": "Salary must be positive" }
+			}
 		}
 	},
 	"folders": {
@@ -599,7 +604,9 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 }
 ```
 
-**Translatable sections (consumed by the installer):** `entities` (+ nested `fields`), `folders`, `views`, `menus` (+ nested `items`), `actions` (+ `params`), `reports` (+ `datasets.caption`, `params`).
+**Translatable sections (consumed by the installer):** `entities` (+ nested `fields` and `constraints`), `folders`, `views`, `menus` (+ nested `items`), `actions` (+ `params`), `reports` (+ `datasets.caption`, `params`).
+
+**Constraint violation messages are localizable (opt-in).** The `message` on a check/unique constraint in the entity JSON is the base (fallback) text. To localize it, add a per-locale override under `entities.<entityCd>.constraints.<constraintName>.message` in each `translations/<locale>.json`. The server resolves it with culture fallback (per-locale → base) and it surfaces identically on the client pre-save validator and the server DB-violation path. Unlike labels, constraint overrides are **not** completeness-enforced: a missing override for a declared `supportedLocales` entry emits a **non-fatal warning** (from `dforge_module_validate` pre-flight and at install) and the base message is used as the fallback.
 
 **Silently ignored at runtime:** `roles` and `print_templates` — the resource rows have no `res_id`, so translations are reserved for future use. `settings` is validated for completeness (when listed in `supportedLocales`) but the registrar does not display the translated labels, so don't expect localized output. Display names for these come from the source manifest (`description` for roles, `label` for print templates and settings).
 

package/skills/dforge-mcp-author/SKILL.md

@@ -116,7 +116,7 @@ Always-on cheat-sheet — enough to author inline; load the linked `references/*
 - **`toString`:** every entity needs one, `{column}` braces, e.g. `"{first_name} {last_name}"`.
 - **Data views:** `dataSources` array at root — never root-level `entityCode` + `columns`. → `data-views.md`
 - **Menus:** leaf items use `dataViewCode` (not `viewCode`); section nodes omit `itemType`; icons are Bootstrap names sans `bi-`. → `menus.md`
-- **Security roles:** `rights` (not `entityRights`); entities `SIUDC`, actions/reports/folders `E`. Rights keys: same-module entity bare (`product`), cross-module entity dotted (`fin.invoice`), and actions/reports/folders use a **colon** prefix — `action:approve`, `report:summary`, `folder:east` (never a dot). Omit a key to deny; never map to `""`. → `security.md`
+- **Security roles:** `rights` (not `entityRights`); entities `SIUDC`, actions/reports/folders `E`. Rights keys: same-module entity bare (`product`), cross-module entity dotted (`fin.invoice`), and actions/reports/folders use a **colon** prefix — `action:approve`, `report:summary`, `folder:east` (never a dot). Omit a key to deny; never map to `""`. `roles.json` carries `description` (English fallback) + `rights` only — **no `label`**; the localized role display name lives in the translation files as `roles.<code>.label` and is completeness-enforced. → `security.md`, `translations.md`
 - **Action script** in `ui/actions.json` = bare filename (no path, no `.dsl`).
 - **Action DSL dates:** inside `execute:` use lowercase `now()`; `TODAY()`/`NOW()` are formula-only (`canExecute:`/formula columns) and are **undefined in `execute:`**. → `action-dsl.md`
 - **SQL placeholders** = `@paramName` (not `:paramName`).
@@ -397,7 +397,7 @@ Key areas (full checklist):
 - **Security**: every entity code in the manifest appears in at least one role's rights map; `rights` key used (not `entityRights`); entity rights use `SIUDC` letters; actions/reports use `E`.
 - **Actions**: every `script` value in `ui/actions.json` is a bare filename (no path, no `.dsl` extension); every action referenced by a trigger or job exists in `ui/actions.json`.
 - **Seed data**: numeric PKs; parent entities loaded before children; no circular references.
-- **Translations**: a `translations/<locale>.json` file exists for every locale in `supportedLocales`; every trait-provided field (`created_at`, `updated_at`, etc.) has a translation entry in each file.
+- **Translations**: a `translations/<locale>.json` file exists for every locale in `supportedLocales` **plus the `en-US` base**; every trait-provided field (`created_at`, `updated_at`, etc.) has a translation entry in each file; a `roles` section carries a `label` for **every** role in `security/roles.json` (completeness-enforced in every locale incl. en-US — keys are module-qualified role codes like `crm.admin`).
 
 ### Step 3 — Translation deferral check
 

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

@@ -144,6 +144,7 @@ var note = params[note]             // no quotes around param name in this DSL
 | `addDays(date, n)` | Date | Add `n` days to a date, e.g. `addDays(now(), 30)`. |
 | `nextNumber('entity')` | String | Generate next value from a number sequence. Usually not needed — platform auto-fills on `insert()`. Use for pre-generating numbers. |
 | `callProc('proc_name', { args })` | Result | Call a stored procedure. Args are passed as named parameters. |
+| `entityLink('entityCd', record, description?)` | Link value | Build a clickable link to any entity record, for storing in an `entitylink` (jsonb) column. `record` is a row object (e.g. the result of `insert()` or `getRecord()`); its PK columns are read and stored as **strings**, so snowflake/cuid ids (> 2^53) stay exact. Optional `description` sets the link's display text. |
 
 > **Dates: `now()` in `execute:`, `TODAY()`/`NOW()` in formulas.** The `execute:` block runs as
 > JavaScript (Jint) and exposes **lowercase `now()`** only — `TODAY()` and `NOW()` (uppercase) are

package/skills/dforge-mcp-author/references/column-types.md

@@ -67,6 +67,26 @@ Plus declare the FK constraint in the entity's `references` block:
 }
 ```
 
+### Referential actions — `onDelete` / `onUpdate` (optional)
+
+A reference entry may declare `onDelete` and/or `onUpdate` to emit an `ON DELETE` / `ON UPDATE` clause on the FK. Both accept: `"cascade"`, `"setNull"`, `"restrict"`, `"noAction"`. **Omitted = `noAction`** (plain FK — the default and correct choice for most references).
+
+```json
+"references": {
+    "FK_OpportunityLine_Opportunity": {
+        "from": { "field": "opportunity_id" },
+        "to":   { "entity": "opportunity", "field": "opportunity_id" },
+        "onDelete": "cascade"
+    }
+}
+```
+
+- **`cascade`** — deleting the parent deletes its children. Use for owned child collections (line items under their header) so the parent delete isn't blocked by a FK violation.
+- **`setNull`** — nulls the FK column when the parent is deleted; the FK column **must be nullable**.
+- **`restrict` / `noAction`** — block the parent delete while children exist (the safe default; leave the keys off to get this).
+- **`onUpdate`** — fires when the parent's key value changes. A **no-op for immutable `cuid` PKs** (identity-trait entities), so only meaningful for entities keyed on a natural/mutable PK.
+- **Self-healing on reinstall:** the DDL generator reads the live FK's current rule and drops+recreates the FK only when it changed, so changing `onDelete` and reinstalling applies to already-provisioned tenants (and is a no-op otherwise). An unknown value fails install fast.
+
 > **FK column `dbDatatype` must exactly match the referenced entity's PK `dbDatatype`.** Never guess.
 > - Entities using the `identity` trait → PK is `dbDatatype: "cuid"` → FK column must also be `"cuid"`
 > - Cross-module or legacy entities → call `dforge_module_inspect` on the referenced module and read the PK column's `dbDatatype` before declaring the FK

package/skills/dforge-mcp-author/references/field-types.md

@@ -65,7 +65,7 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `lookup` | `guid` | `R` | Reference to another entity (always paired with a hidden FK column — see SKILL.md "FK+Reference pattern") |
 | `user` | `cuid` | `D` | User picker. Writes a user ID directly, no paired FK needed. |
 | `grid` | `set` | `S` | Detail grid of related records (1:N backwards reference). Used with `link` declaring the relation. |
-| `entitylink` | `json` | `D` | Polymorphic link to any entity (stores `{entity, id}` pair). |
+| `entitylink` | `json` | `D` | Polymorphic link to any entity (stores `{entity, id}` pair). Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in (see `action-dsl.md`). |
 
 ## JSON
 

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

@@ -134,6 +134,8 @@ Check constraints use a subset of the formula grammar. The server parses them to
 [email] LIKE '%@%'
 ```
 
+The constraint's `message` (the violation text shown to users) is **localizable** — add a per-locale override at `entities.<entityCd>.constraints.<constraintName>.message` in each `translations/<locale>.json`. The base `message` in the entity JSON is the fallback. See `translations.md` → "Constraint violation messages ARE translatable".
+
 ## Examples — full formula columns
 
 ### Full name

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

@@ -14,7 +14,11 @@ Lives in: `security/roles.json`
 
 ## Role definition
 
-Role codes use a `module.role` naming pattern (e.g. `crm.admin`, `crm.sales-rep`):
+Role codes use a `module.role` naming pattern (e.g. `crm.admin`, `crm.sales-rep`).
+
+> **Role display name & translations.** Each role has exactly two keys: `description` and `rights` (`roles.schema.json` is `additionalProperties: false` — **do not** add a `label` here). `description` is the English fallback display name. The **localized** display name lives in the translation files as `roles.<code>.label`, keyed by the module-qualified role code, and is **completeness-enforced**: every role must have a `roles.<code>.label` in every `translations/<locale>.json` (including the `en-US` base) or install fails. See `translations.md`.
+
+Example:
 
 ```json
 {

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

@@ -33,6 +33,10 @@ Translation files mirror the module's content structure. Each translatable objec
     "folders": {
         "crm": { "label": "Sales CRM" }
     },
+    "roles": {
+        "crm.admin": { "label": "CRM Administrator" },
+        "crm.sales-rep": { "label": "Sales Representative" }
+    },
     "views": {
         "contacts": { "label": "Contacts" },
         "contacts_list": { "label": "Contact List" },
@@ -75,14 +79,49 @@ 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`) |
 | `menus` | Menu node labels (root + nested items) | Menu root key → `{ label, items: { item_code: { label } } }` matching `ui/menus.json` structure |
 | `actions` | Action labels, descriptions, and param labels | Action codes (keys from `ui/actions.json`) → `{ label, desc, params: { param_cd: { label } } }` |
 | `reports` | Report dataset captions and param labels | Report codes → `{ datasets: { ds_cd: { caption } }, params: { param_cd: { label } } }` |
+| `entities.<e>.constraints` | Check/unique constraint violation messages (opt-in — warned, not enforced) | Constraint codes → `{ message }` under the owning entity |
+
+### Constraint violation messages ARE translatable (opt-in)
+
+A check/unique constraint declares a user-facing `message` in the entity JSON (`constraints.<name>.message`). That message is the **base/fallback text**. To localize it, add a per-locale override under `entities.<entityCd>.constraints.<constraintName>.message`:
+
+```json
+"entities": {
+    "employee": {
+        "constraints": {
+            "chk_salary_positive": { "message": "Gehalt muss positiv sein" },
+            "UQ_employee_code":    { "message": "Mitarbeiter-Code muss eindeutig sein" }
+        }
+    }
+}
+```
+
+- The server resolves the message with culture fallback — **per-locale override → base message from the entity JSON**. `EntityMetadataLoader` reads `COALESCE(culture_res.label, resource.label, entity_constrains.description)`, so the same override surfaces on the client pre-save `CheckConstraints` validator and the server DB-violation (23514) path.
+- **Opt-in, never mandatory** (unlike roles/labels, which completeness *enforces*). If the manifest lists `supportedLocales` and a constraint `message` has no override for one of those (non-English) locales, install emits a **non-fatal warning** naming the missing `entities.<e>.constraints.<c>.message` keys (printed by the CLI, returned in the marketplace install response). Install still commits with the base message as the fallback. `dforge_module_validate` surfaces the same gap pre-flight as a warning.
+- Only constraints that declare a `message` are scanned; English (`en`/`en-*`) is the base and is never warned; extension entities (`"extends": "..."`) are skipped — their constraint translations belong with the foreign module's files.
+
+### Roles ARE translated — and completeness is enforced
+
+Role labels are **required and localized** (this changed — older docs said roles were skipped; they are not). `SecurityRegistrar` gives every role a `res_id`, so `TranslationRegistrar` wires the role label exactly like entities/views/menus:
+
+```json
+"roles": {
+    "crm.admin":      { "label": "CRM Administrator" },
+    "crm.sales-rep":  { "label": "Sales Representative" }
+}
+```
+
+- **Keys are the role codes** from `security/roles.json` — already module-qualified (e.g. `crm.admin`, `crm.sales-rep`). They match `module_role.name`.
+- **Value is `{ "label": ... }`** — the localized display name. It supersedes the `description` from `roles.json` at runtime; `description` remains the English fallback if a role has no translation entry.
+- **Completeness is enforced.** `TranslationCompletenessValidator` requires `roles.<code>.label` for **every** role in `security/roles.json`, in **every** translation file — including the `en-US` base. A missing role label fails install with `Label for role '<code>'.` So ship a `roles` block with a label for each role in **each** `translations/<locale>.json` (en-US + every locale in `supportedLocales`).
 
 ### Sections that are NOT translated (write-time only)
 
-- `roles` — role rows have no `res_id` column. The `roles` key may appear in shipped translation files (e.g. `modules/crm/translations/de-DE.json`) but is **explicitly skipped** by the installer. Role display name comes from `security/roles.json` `description` only. (Comment in [`TranslationRegistrar.cs:248`](../../../server/src/dForge.Admin/Services/ModuleInstall/TranslationRegistrar.cs#L248): "reserved for future use.")
 - `settings` — completeness *is* checked by the validator when listed in `manifest.supportedLocales` (so you'll be forced to ship `settings.<cd>.label` for each declared locale), but the registrar doesn't display those translated labels at runtime. The English `label` in `settings.json` is what users see today.
 - `print_templates` — not currently consumed by the registrar. Template labels come from `ui/print_templates.json`.
 
@@ -112,6 +151,10 @@ If you include these sections, the install succeeds (they're silently ignored)
     "folders": {
         "crm": { "label": "Vertrieb CRM" }
     },
+    "roles": {
+        "crm.admin": { "label": "CRM-Administrator" },
+        "crm.sales-rep": { "label": "Vertriebsmitarbeiter" }
+    },
     "views": {
         "contacts": { "label": "Kontakte" }
     },
@@ -144,12 +187,13 @@ Every listed locale MUST have a matching `translations/<locale>.json` with a lab
 
 1. **Always provide `en-US`** as the base language. Other languages fall back to it for missing keys.
 2. **Locale format is `ll-CC`** (e.g. `en-US`, `de-DE`, `fr-FR`) — language code + country code, hyphen-separated.
-3. **Translate everything user-visible**: entity labels, every field label (including trait-provided fields like `created_date`, `last_updated`), view names, menu items, action labels, role descriptions, setting labels, folder names.
+3. **Translate everything user-visible**: entity labels, every field label (including trait-provided fields like `created_date`, `last_updated`), view names, menu items, action labels, **role labels (required — completeness-enforced, `roles.<code>.label` for every role in every locale incl. en-US)**, setting labels, folder names.
 4. **Include virtual columns** (references, sets, formulas) in field translations — they appear in the UI just like physical columns.
 5. **Menu translations mirror the `ui/menus.json` structure** — root key → `items` → nested items.
 6. **Missing keys fall back** to the `en-US` value, then to the raw code name. So it's safe to ship partial translations — untranslated items show in English rather than breaking.
 7. **Don't translate column codes** — only the `label` values. Codes stay as-is in all languages.
 8. **File naming**: `translations/<locale>.json` (e.g. `de-DE.json`) — each non-English file must match a locale listed in `supportedLocales`.
+9. **Constraint messages are opt-in** — localize them under `entities.<e>.constraints.<c>.message` when you want a per-locale violation message; otherwise the base `message` from the entity JSON is used. Missing overrides warn (non-fatal), they don't fail install. See "Constraint violation messages ARE translatable" above.
 
 ## When to create translations
 

package/skills/dforge-mcp-author/references/validation-checklist.md

@@ -90,7 +90,7 @@ For each entity:
 ## Security
 
 - [ ] `security/roles.json` exists (at least one role)
-- [ ] Every role has `description` and `rights` (both required; no `label` field — display name comes from `description`). The `roles.schema.json` sets `additionalProperties: false`, so any extra field (including `label`) is rejected at install time.
+- [ ] Every role has `description` and `rights` (both required; no `label` field in `roles.json` — the `roles.schema.json` sets `additionalProperties: false`, so any extra field including `label` is rejected here). `description` is the English display-name fallback; **localized role labels live in the translation files** (`roles.<code>.label`) and are completeness-enforced — see Translations below.
 - [ ] The field name is `rights`, NOT `entityRights`
 - [ ] Rights strings use only valid letters: `SIUDC` for entities, `E` for actions/reports/folders
 - [ ] Entity codes in `rights` all reference real entities (in this module or dependencies)
@@ -132,7 +132,8 @@ For each action:
 - [ ] Has `views` section with labels for every data view
 - [ ] Has `menus` section matching the `ui/menus.json` structure
 - [ ] Has `actions` section with labels for every action
-- [ ] Has `roles` section with labels for every role
+- [ ] Has `roles` section with a `label` for **every** role in `security/roles.json` (completeness-enforced — a missing role label fails install; keys are the module-qualified role codes, e.g. `crm.admin`)
+- [ ] (Optional) Constraint messages localized under `entities.<e>.constraints.<c>.message` — opt-in; a missing override for a declared `supportedLocales` entry warns (surfaced by `dforge_module_validate` and at install) but does not fail install
 - [ ] Has `settings` section with labels for every setting (if settings exist)
 - [ ] Has `folders` section with label for the root folder
 - [ ] Additional language files (if any) have the same structure as `en-US.json`