@dforge-core/dforge-mcp 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.4",
+	"version": "0.1.6",
 	"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",
@@ -32,7 +32,7 @@
 	},
 	"dependencies": {
 		"@dforge-core/dforge-cli": "^0.2.2",
-		"@dforge-core/metadata": "^0.0.4",
+		"@dforge-core/metadata": "^0.0.5",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"zod": "^4.4.3"
 	},

package/resources/schemas/reports.schema.json

@@ -52,7 +52,7 @@
 				"vizType": {
 					"type": "string",
 					"enum": ["table", "chart", "kpi", "pivot", "tree", "markdown"],
-					"description": "Visualization type. (Older packages may use `metric` for `kpi`.)"
+					"description": "Visualization type. For any chart the vizType is `chart`; the chart kind goes in `config.chartType`."
 				},
 				"datasetCd": {
 					"type": "string",
@@ -61,9 +61,142 @@
 				"title": { "type": "string" },
 				"config": {
 					"type": "object",
-					"description": "Viz-type-specific configuration.\n- chart: { chartType ('bar'|'horizontalBar'|'stackedBar'|'combo'|'line'|'area'|'pie'|'doughnut'|'scatter'|'bubble'|'funnel'|'heatmap'), categoryCol, valueCol, agg, seriesCol?, sizeCol?, chartSize? ('sm'|'m'|'l'|'xl'), clickAction?, showTrend?, series? }. `series` (a single object OR an array) declares CROSS-SOURCE overlay series on bar/horizontalBar/line/area, each { source?, categoryCol, valueCol, agg, label? }; `source` names a sibling dataset code (omit = the panel's own dataset). Overlays share one category axis (union of category values; bar gaps fill 0, line/area gap with null).\n- kpi: { metrics: [ metric, ... ] }. Each metric is EITHER an aggregation metric { column, agg ('sum'|'avg'|'min'|'max'|'count'), display?, label?, target?, min?, max?, icon?, sparklineDimension? } OR a FORMULA metric { formula (e.g. '[won] / [all] * 100'), inputs: [ { alias, column, agg, source? } ], format?: { style?: 'number'|'percent', decimals? }, display?, label? }. A formula input's `source` names a sibling dataset code for CROSS-DATASET metrics (omit = the panel's own dataset). Auto format (omit `format.style`) inherits the first input column's own formatter (currency/grouping).\n- table: { groupRules, aggregations, colorRules }."
+					"description": "Viz-type-specific configuration. `kpi` and `chart` are structurally validated (see kpiConfig / chartConfig below); `table`/`pivot`/`tree`/`markdown` accept any object."
 				}
 			},
+			"additionalProperties": false,
+			"allOf": [
+				{
+					"if": { "required": ["vizType"], "properties": { "vizType": { "const": "kpi" } } },
+					"then": { "properties": { "config": { "$ref": "#/$defs/kpiConfig" } } }
+				},
+				{
+					"if": { "required": ["vizType"], "properties": { "vizType": { "const": "chart" } } },
+					"then": { "properties": { "config": { "$ref": "#/$defs/chartConfig" } } }
+				}
+			]
+		},
+
+		"aggFunc": {
+			"type": "string",
+			"enum": ["sum", "avg", "min", "max", "count"],
+			"description": "Aggregation function."
+		},
+
+		"kpiConfig": {
+			"type": "object",
+			"description": "KPI panel config: one or more metric cards.",
+			"required": ["metrics"],
+			"properties": {
+				"metrics": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/kpiMetric" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"kpiMetric": {
+			"type": "object",
+			"description": "A KPI metric — EITHER an aggregation metric (`column` + `agg`, and no formula/inputs) OR a formula metric (`formula` + `inputs`, and no column/agg).",
+			"properties": {
+				"column": { "type": "string", "description": "Column to aggregate (aggregation metric)." },
+				"agg": { "$ref": "#/$defs/aggFunc" },
+				"formula": { "type": "string", "description": "Expression over `[alias]` inputs, e.g. '[won] / [all] * 100' (formula metric)." },
+				"inputs": {
+					"type": "array",
+					"minItems": 1,
+					"description": "Named aggregation inputs the formula references by `[alias]`.",
+					"items": { "$ref": "#/$defs/kpiInput" }
+				},
+				"format": { "$ref": "#/$defs/metricFormat" },
+				"display": { "type": "string", "enum": ["value", "gauge", "progress", "sparkline", "icon"] },
+				"label": { "type": "string" },
+				"target": { "type": "number" },
+				"min": { "type": "number" },
+				"max": { "type": "number" },
+				"icon": { "type": "string" },
+				"sparklineDimension": { "type": "string" }
+			},
+			"additionalProperties": false,
+			"allOf": [
+				{
+					"if": { "required": ["formula"] },
+					"then": {
+						"required": ["formula", "inputs"],
+						"not": { "anyOf": [ { "required": ["column"] }, { "required": ["agg"] } ] }
+					},
+					"else": {
+						"required": ["column", "agg"],
+						"not": { "anyOf": [ { "required": ["formula"] }, { "required": ["inputs"] } ] }
+					}
+				}
+			]
+		},
+
+		"kpiInput": {
+			"type": "object",
+			"description": "One named aggregation a formula metric references by `[alias]`.",
+			"required": ["alias", "column", "agg"],
+			"properties": {
+				"alias": { "type": "string", "description": "Token used in the formula as `[alias]`." },
+				"column": { "type": "string" },
+				"agg": { "$ref": "#/$defs/aggFunc" },
+				"source": { "type": "string", "description": "Sibling dataset code to aggregate over (CROSS-DATASET); omit = the panel's own dataset." }
+			},
+			"additionalProperties": false
+		},
+
+		"metricFormat": {
+			"type": "object",
+			"description": "Formula-result format. OMIT for Auto — inherits the first input column's own formatter (currency/grouping).",
+			"properties": {
+				"style": { "type": "string", "enum": ["number", "percent"] },
+				"decimals": { "type": "integer", "minimum": 0 }
+			},
+			"additionalProperties": false
+		},
+
+		"chartConfig": {
+			"type": "object",
+			"description": "Chart panel config. The chart kind is `chartType`; the panel `vizType` is always `chart`.",
+			"required": ["chartType", "categoryCol", "valueCol"],
+			"properties": {
+				"chartType": {
+					"type": "string",
+					"enum": ["bar", "horizontalBar", "stackedBar", "combo", "line", "area", "pie", "doughnut", "scatter", "bubble", "funnel", "heatmap"]
+				},
+				"categoryCol": { "type": "string" },
+				"valueCol": { "type": "string" },
+				"agg": { "$ref": "#/$defs/aggFunc" },
+				"seriesCol": { "type": "string", "description": "Split-by dimension (same dataset)." },
+				"sizeCol": { "type": "string", "description": "Bubble radius column." },
+				"chartSize": { "type": "string", "enum": ["sm", "m", "l", "xl"] },
+				"clickAction": { "type": "string", "enum": ["crossFilter", "drillThrough", "none"] },
+				"showTrend": { "type": "boolean" },
+				"series": {
+					"description": "CROSS-SOURCE overlay series (bar/horizontalBar/line/area) — a single series OR an array. Each aligns on the shared category axis.",
+					"oneOf": [
+						{ "$ref": "#/$defs/chartSeries" },
+						{ "type": "array", "items": { "$ref": "#/$defs/chartSeries" } }
+					]
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"chartSeries": {
+			"type": "object",
+			"description": "One cross-source overlay series.",
+			"required": ["categoryCol", "valueCol", "agg"],
+			"properties": {
+				"source": { "type": "string", "description": "Sibling dataset code; omit = the panel's own dataset." },
+				"categoryCol": { "type": "string" },
+				"valueCol": { "type": "string" },
+				"agg": { "$ref": "#/$defs/aggFunc" },
+				"label": { "type": "string" }
+			},
 			"additionalProperties": false
 		},
 
@@ -140,11 +273,13 @@
 				"leafKey": { "type": "string", "description": "Column on the query entity identifying the tree node a row belongs to (e.g. 'account_id' on balance_register)." },
 				"measures": {
 					"type": "array",
+					"minItems": 1,
 					"items": { "type": "string" },
 					"description": "Value column codes (on the query entity) to SUM into ancestors. Must be additively-rollable."
 				},
 				"labels": {
 					"type": "array",
+					"minItems": 1,
 					"items": { "type": "string" },
 					"description": "Node-describing columns, expressed as the report column keys ('account.account_code'). Sourced from the tree entity's physical column (the segment after the dot); emitted under the same key so the report layout is unchanged."
 				},

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/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,29 @@ 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 } } }` |
 
+### 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 +131,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,7 +167,7 @@ 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.

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,7 @@ 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`)
 - [ ] 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`