@dforge-core/dforge-mcp 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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.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,29 @@ var SYSTEM_ENTITY_PK = {
   menu_item: "menu_item_id",
   resource: "resource_id"
 };
+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 = [];
@@ -33992,6 +34062,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.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/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

@@ -133,6 +133,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`