@dforge-core/dforge-mcp 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.1.8
+
+### Added
+- **`dforge_module_validate` now flags a grid-style data view over an entity
+  with no visible column.** Errors when a column-rendering view (grid, list,
+  kanban, calendar, gallery, tree-grid, master-detail, or the default) draws an
+  own-module entity that has no *visible scalar column* — a field whose `flags`
+  include `V` and whose `columnType` isn't a set (`S`). Without one the view
+  renders the runtime empty state *"No visible columns configured for this
+  entity."* This mirrors the server's install-time `DataViewVisibleColumnValidator`,
+  so authors catch it pre-flight instead of at pack/install. Column-agnostic view
+  types (`diagram`, `matrix`, `library`) are exempt; cross-module entities are
+  skipped; the check runs after trait expansion so a trait-contributed `V` field
+  counts.
+
+### Skill
+- `dforge-mcp-author`: documented the **visible-column requirement** for
+  column-rendering data views. `references/data-views.md` gains a "the entity
+  needs a visible column" rule (visibility is entity-driven via the `V` flag, not
+  the view's `columns` array) plus common-mistake bullets, and
+  `references/validation-checklist.md` gains matching checklist/red-flag entries.
+
+## 0.1.7
+
+### Changed
+- Bumped `@dforge-core/dforge-cli` to `^0.2.7`. Picks up the corrected module
+  scaffolder (`buildTranslations` now emits the nested runtime format with the
+  completeness-required `roles` block and opt-in constraint-message localization,
+  replacing the non-functional flat shape) and the native CLI's install-time
+  untranslated-constraint warning.
+
+### Added
+- **`dforge_module_validate` now flags untranslated check/unique constraint
+  messages.** When the manifest declares `supportedLocales`, the validator
+  warns (never errors) for every constraint that declares a `message` but has no
+  `entities.<e>.constraints.<c>.message` override in a declared non-English
+  locale file. This mirrors the server's install-time `UntranslatedConstraint`
+  scan, so authors catch the gap pre-flight instead of at install. English
+  locales and extension entities (`extends`) are skipped; the locale file is
+  matched case-insensitively (`de-de.json` satisfies `de-DE`). Opt-in — modules
+  without `supportedLocales` are not scanned.
+
+### Skill
+- `dforge-mcp-author`: documented **localizable constraint violation messages**.
+  A constraint's `message` in the entity JSON is the base/fallback text; a
+  per-locale override under `entities.<e>.constraints.<c>.message` in
+  `translations/<locale>.json` localizes it (culture fallback: per-locale →
+  base), surfacing identically on the client pre-save validator and the server
+  DB-violation path. Localization is opt-in (warned, not completeness-enforced)
+  (`translations.md`, `formulas.md`, `validation-checklist.md`,
+  `resources/docs/conventions.md`).
+
 ## 0.1.6
 
 ### Skill

package/dist/server.js

@@ -30954,7 +30954,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.2/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.7/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -30982,13 +30982,25 @@ function buildManifest(opts, moduleId) {
 }
 function buildEntity(entity) {
   const traits2 = entity.traits === "identity+audit" ? ["identity", "audit"] : ["identity"];
-  return {
+  const built = {
     description: entity.label,
     dbObject: entity.name,
     toString: "{id}",
     traits: traits2,
     fields: {}
   };
+  if (entity.constraints?.length) {
+    built.constraints = Object.fromEntries(
+      entity.constraints.map((c) => {
+        const def = { type: c.type ?? "check" };
+        if (c.expression !== void 0) def.expression = c.expression;
+        if (c.fields !== void 0) def.fields = c.fields;
+        def.message = c.message;
+        return [c.name, def];
+      })
+    );
+  }
+  return built;
 }
 function buildDataViews(entities) {
   const views = {};
@@ -31056,15 +31068,50 @@ function buildSettings() {
   return {};
 }
 function buildTranslations(opts) {
-  const t = {};
-  t[`module.${opts.code}.label`] = opts.displayName;
-  if (opts.description) t[`module.${opts.code}.description`] = opts.description;
+  const entities = {};
   for (const e of opts.entities) {
-    t[`entity.${e.name}.label`] = e.label;
-    t[`view.${e.name}.label`] = e.label;
-    t[`menu.${e.name}.label`] = e.label;
+    const fields = {
+      // identity trait → primary key column
+      [`${e.name}_id`]: { label: `${e.label} ID` }
+    };
+    if (e.traits === "identity+audit") {
+      fields.created_date = { label: "Created Date" };
+      fields.last_updated = { label: "Last Updated" };
+    }
+    const entityEntry = { label: e.label };
+    if (opts.description && opts.entities.length === 1) {
+      entityEntry.desc = opts.description;
+    }
+    entityEntry.fields = fields;
+    if (e.constraints?.length) {
+      entityEntry.constraints = Object.fromEntries(
+        e.constraints.map((c) => [c.name, { message: c.message }])
+      );
+    }
+    entities[e.name] = entityEntry;
   }
-  return t;
+  return {
+    entities,
+    folders: {
+      // folders.json root folder key is the module code (see buildFolders).
+      [opts.code]: { label: opts.displayName }
+    },
+    roles: {
+      // Role labels are completeness-enforced in every locale incl. en-US.
+      [`${opts.code}.admin`]: { label: `${opts.displayName} Administrator` }
+    },
+    views: Object.fromEntries(
+      opts.entities.map((e) => [e.name, { label: e.label }])
+    ),
+    menus: {
+      [`${opts.code}_menu`]: {
+        label: opts.displayName,
+        items: Object.fromEntries(
+          opts.entities.map((e) => [e.name, { label: e.label }])
+        )
+      }
+    }
+  };
 }
 function buildSeedData() {
   return [];
@@ -33855,6 +33902,38 @@ var SYSTEM_ENTITY_PK = {
   menu_item: "menu_item_id",
   resource: "resource_id"
 };
+var COLUMN_AGNOSTIC_VIEW_TYPES = /* @__PURE__ */ new Set(["diagram", "matrix", "library"]);
+function hasVisibleScalarColumn(fields) {
+  for (const f of Object.values(fields)) {
+    if (!f || typeof f !== "object") continue;
+    const flags = typeof f.flags === "string" ? f.flags : "";
+    if (flags.includes("V") && f.columnType !== "S") return true;
+  }
+  return false;
+}
+function resolveTranslationFile(translationsDir, locale) {
+  const exact = path10.join(translationsDir, `${locale}.json`);
+  if (fs8.existsSync(exact)) return exact;
+  if (!fs8.existsSync(translationsDir)) return void 0;
+  const want = `${locale}.json`.toLowerCase();
+  for (const f of fs8.readdirSync(translationsDir)) {
+    if (f.toLowerCase() === want) return path10.join(translationsDir, f);
+  }
+  return void 0;
+}
+function hasConstraintOverride(root, entityCd, constraintCd) {
+  if (!root || typeof root !== "object") return false;
+  const entities = root.entities;
+  if (!entities || typeof entities !== "object") return false;
+  const entity = entities[entityCd];
+  if (!entity || typeof entity !== "object") return false;
+  const constraints = entity.constraints;
+  if (!constraints || typeof constraints !== "object") return false;
+  const ck = constraints[constraintCd];
+  if (!ck || typeof ck !== "object") return false;
+  const msg = ck.message;
+  return typeof msg === "string" && msg.trim() !== "";
+}
 function moduleValidate(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
   const issues = [];
@@ -33863,6 +33942,7 @@ function moduleValidate(args) {
   const entityMap = manifest.entities ?? {};
   const entities = {};
   const columnsOf = {};
+  const fieldDefsOf = {};
   for (const [name, relPath] of Object.entries(entityMap)) {
     if (name.includes(".")) continue;
     const abs = path10.join(paths.root, relPath.replace(/^\.\//, ""));
@@ -33880,12 +33960,15 @@ function moduleValidate(args) {
     entities[name] = e;
     const fields = e.fields ?? {};
     const cols = new Set(Object.keys(fields));
+    let traitFields = {};
     const traits2 = e.traits ?? [];
     try {
-      for (const c of Object.keys(expandTraits(traits2, name))) cols.add(c);
+      traitFields = expandTraits(traits2, name);
+      for (const c of Object.keys(traitFields)) cols.add(c);
     } catch {
     }
     columnsOf[name] = cols;
+    fieldDefsOf[name] = { ...traitFields, ...fields };
   }
   const deps = new Set(Object.keys(manifest.dependencies ?? {}));
   const isKnownEntity = (code2) => {
@@ -33954,6 +34037,27 @@ function moduleValidate(args) {
       }
     }
   }
+  const vcSeen = /* @__PURE__ */ new Set();
+  for (const [vcode, v] of Object.entries(views)) {
+    const sources = v.dataSources ?? [];
+    if (sources.length === 0) continue;
+    const viewType = v.viewType ?? "grid";
+    if (COLUMN_AGNOSTIC_VIEW_TYPES.has(viewType)) continue;
+    for (const s of sources) {
+      const ent = s.entityCode;
+      if (!ent) continue;
+      const defs = fieldDefsOf[ent];
+      if (!defs) continue;
+      if (hasVisibleScalarColumn(defs)) continue;
+      const key = `${vcode}\0${ent}`;
+      if (vcSeen.has(key)) continue;
+      vcSeen.add(key);
+      err(
+        `data_views \u2192 ${vcode}`,
+        `view (${viewType}) renders entity '${ent}', which has no visible column \u2014 mark at least one of its fields visible with the 'V' flag (set columns / columnType 'S' don't count for a grid)`
+      );
+    }
+  }
   const menus = readJsonOrDefault(paths.menus, {});
   const walk = (node, where) => {
     if (!node || typeof node !== "object") return;
@@ -33992,6 +34096,50 @@ function moduleValidate(args) {
     }
   } catch {
   }
+  const supportedLocales = Array.isArray(manifest.supportedLocales) ? manifest.supportedLocales.filter((l) => typeof l === "string") : [];
+  if (supportedLocales.length > 0) {
+    const declared = [];
+    for (const [name, e] of Object.entries(entities)) {
+      if (typeof e.extends === "string" && e.extends) continue;
+      const constraints = e.constraints;
+      if (!constraints || typeof constraints !== "object") continue;
+      for (const [cname, c] of Object.entries(constraints)) {
+        if (!c || typeof c !== "object") continue;
+        const msg = c.message;
+        if (typeof msg === "string" && msg.trim() !== "") {
+          declared.push({ entity: name, constraint: cname, message: msg });
+        }
+      }
+    }
+    if (declared.length > 0) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const raw of supportedLocales) {
+        const locale = raw.trim();
+        if (!locale) continue;
+        const lc = locale.toLowerCase();
+        if (lc === "en" || lc.startsWith("en-")) continue;
+        if (seen.has(lc)) continue;
+        seen.add(lc);
+        let tx = null;
+        const abs = resolveTranslationFile(paths.translationsDir, locale);
+        if (abs) {
+          try {
+            tx = JSON.parse(fs8.readFileSync(abs, "utf8"));
+          } catch {
+            tx = null;
+          }
+        }
+        for (const d of declared) {
+          if (!hasConstraintOverride(tx, d.entity, d.constraint)) {
+            warn(
+              `translations/${locale}.json`,
+              `constraint message '${d.entity}.constraints.${d.constraint}.message' has no ${locale} override \u2014 the base message ("${d.message}") will be used as the fallback. Add entities.${d.entity}.constraints.${d.constraint}.message to localize it.`
+            );
+          }
+        }
+      }
+    }
+  }
   const errors = issues.filter((i) => i.level === "error");
   const warnings = issues.filter((i) => i.level === "warning");
   const clean = errors.length === 0 && warnings.length === 0;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.6",
+	"version": "0.1.8",
 	"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/references/data-views.md

@@ -58,6 +58,28 @@ Lives in: `ui/data_views.json`
 }
 ```
 
+## Critical rule — the entity needs a visible column
+
+A grid-style view can only render an entity that has at least one **visible scalar column** — a field whose `flags` include `V` and whose `columnType` is **not** a set (`S`). Column visibility is entity-driven (the field's flags), **not** view-driven: the `columns` array inside `dataSources[]` is layout-only (reorder/pin/width among already-visible fields) — it can't make a non-`V` field appear.
+
+If none of an entity's fields are visible (or only its set/child-collection columns are), the view renders the runtime empty state *"No visible columns configured for this entity."* — a broken screen the user only hits when they open the menu item. `dforge_module_validate` and `dforge_module_pack` now **reject** this before install.
+
+```jsonc
+// WRONG — grid over an entity whose fields are all hidden (no "V")
+"fields": {
+    "code": { "fieldTypeCd": "text", "flags": "EM" },   // E=editable, M=… but no V
+    "lines": { "columnType": "S", "flags": "VEM" }        // visible, but a SET — doesn't count for a grid
+}
+// RIGHT — at least one visible scalar field
+"fields": {
+    "code": { "fieldTypeCd": "text", "flags": "VEM" }     // V present, not a set → satisfies the grid
+}
+```
+
+This applies to every column-rendering view type (grid, list, kanban, calendar, gallery, tree-grid, master-detail, and the default). The column-agnostic types — `diagram`, `matrix`, `library` — draw from `viewConfig`/relationships instead, so they're **exempt** from this rule.
+
+See [flags.md](flags.md) for the flag string, [column-types.md](column-types.md) for `columnType` (`R`/`S`/`F`).
+
 ## View types
 
 | `viewType` | Description | `viewConfig` | When to use |
@@ -243,3 +265,4 @@ Most views only have one source. Order is view-level and applies to the primary
 - Object-array order like `[{ column_cd: "...", direction: "asc" }]` — **wrong shape for data views**. Use `string[]` with leading `-` for descending.
 - `viewType` is **optional** — omitted or unknown values fall back to `grid` at runtime. Set it explicitly for any non-grid view (`kanban`, `calendar`, `matrix`, …); a `matrix` view also **requires** a `viewConfig` with `rowAxis`/`colAxis`/`cell`.
 - Inventing view types like `"spreadsheet"` or `"table"` — **wrong**. Use `grid`.
+- A grid-style view over an entity with **no visible scalar column** (no field flagged `V`, or only set columns) — **rejected** at validate/pack. Mark at least one non-set field visible. See the [critical rule above](#critical-rule--the-entity-needs-a-visible-column). `diagram`/`matrix`/`library` are exempt.

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/translations.md

@@ -84,6 +84,26 @@ Translation files mirror the module's content structure. Each translatable objec
 | `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
 
@@ -173,6 +193,7 @@ Every listed locale MUST have a matching `translations/<locale>.json` with a lab
 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

@@ -72,6 +72,7 @@ For each entity:
 - [ ] Each source has `entityCode` and `columns`
 - [ ] `entityCode` points to an entity that exists
 - [ ] Column codes in `columns` all exist on the entity
+- [ ] The rendered entity has **at least one visible scalar column** (a field with `V` in `flags`, `columnType` not `S`) — a grid/list/kanban/etc. view over an entity whose fields are all hidden (or only sets) is **rejected** at validate/pack and would render "No visible columns configured for this entity." `diagram`/`matrix`/`library` are exempt
 - [ ] If set, `viewType` is from the supported list (`grid`, `list`, `kanban`, `calendar`, `gallery`, `tree-grid`, `diagram`, `master-detail`, `library`, `matrix`)
 - [ ] A `matrix` view has a `viewConfig` with `rowAxis`, `colAxis`, and `cell` (cell `entity` matches the primary `dataSources` entity; `rowKey`/`colKey` are real cell columns)
 - [ ] Sort uses the view-def-root `order` key — a `string[]` like `["-created_date", "name"]` (leading `-` = descending), NOT `sort` / `[{column_cd, direction}]` (that object shape belongs to queries & reports, not data views)
@@ -133,6 +134,7 @@ For each action:
 - [ ] Has `menus` section matching the `ui/menus.json` structure
 - [ ] Has `actions` section with labels for every action
 - [ ] 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`
@@ -171,6 +173,7 @@ If you see any of these, stop and investigate:
 - Menus with `children: [...]` (array, not dict)
 - Roles with `entityRights` (wrong key)
 - Data views with root-level `entityCode` (should be inside `dataSources`)
+- A grid/list/kanban/etc. view over an entity with no field flagged `V` (or only set columns visible) — rejected at validate/pack
 - Formula columns without `baseDatatypeCd`
 - DSL actions with JavaScript/Python syntax
 - Seed data files without numbered prefixes