@dforge-core/dforge-mcp 0.2.26 → 0.2.28

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.2.28
+
+**`dforge_module_validate` reported a clean module that `pack` then rejected**
+(dForge-core#1184). A field code starting with `_`, a trigger firing a `batch` action, and a
+trigger whose action is bound to another entity all passed. The tool now also runs the
+CLI's static checks (`dforge module validate --json`), the same set `pack` runs, so a rule
+added to the platform reaches this tool without a copy here. A failed check is an error
+under `cli: <check name>`; the CLI's warnings are passed through.
+
+- Needs `@dforge-core/dforge-cli` 0.2.22 or later, which adds `--json`; the dependency is
+  now `^0.2.22`. With an older CLI, or none, the tool still runs its offline checks and adds
+  a `cli` warning that the CLI checks were skipped.
+
+## 0.2.27
+
+**`dforge://reference/formulas` told authors that one-hop navigation is synchronous and
+"resolved instantly".** It is not: on the record card and in grids every `[ref].[field]`
+resolves after the initial load. Read at face value, it made a self-referencing
+`toString` — `[parent].[name]` behind a `{display_path}` placeholder — look safe, and in
+platform builds before dForge-core#1247 that pattern froze the browser. The reference now
+states the real rule, and the sync/async section says which is which.
+
+- **Text `+` with a NULL side gives NULL**, on the card and in reports alike — documented,
+  with `COALESCE` / `IF` for a part that may be missing. The platform's client used to join
+  the NULL as empty text while SQL returned NULL; dForge-core#1247 made them agree.
+- **New "Computed toString" example.** A `toString` placeholder may name a formula column,
+  and it now renders everywhere the display does. Evaluated for the `toString`, text `+`
+  joins a NULL side as empty text so a caption never goes blank — which is why the
+  hierarchy-path example tests the parent with `IF`, not `COALESCE(a + b, c)`.
+- `dforge-module-build` points from its `toString` rule to that example.
+
 ## 0.2.26
 
 `logic/stored_procedures.json` is now something this server can describe. It had no

package/dist/server.js

@@ -31002,7 +31002,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.20/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.22/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -33208,6 +33208,22 @@ function run(args, cwd) {
     command: [cli.display, ...args].join(" ")
   };
 }
+var cliValidate = (moduleDir) => {
+  let r;
+  try {
+    r = run(["module", "validate", moduleDir, "--json"]);
+  } catch (e) {
+    return { unavailable: e.message };
+  }
+  try {
+    const report = JSON.parse(r.stdout.trim());
+    if (Array.isArray(report.checks)) return { report };
+  } catch {
+  }
+  return {
+    unavailable: `${r.command} did not print a JSON report (exit ${r.code}) \u2014 the CLI is probably older than --json support. Update @dforge-core/dforge-cli.`
+  };
+};
 var packModuleSchema = {
   moduleDir: external_exports.string().describe("Path to module directory (containing manifest.json)."),
   outPath: external_exports.string().optional().describe("Output file or directory. Defaults to cwd, naming the file <code>-<version>.dforge.")
@@ -37024,7 +37040,7 @@ function hasConstraintOverride(root, entityCd, constraintCd) {
   const msg = ck.message;
   return typeof msg === "string" && msg.trim() !== "";
 }
-function moduleValidate(args) {
+function moduleValidate(args, cli) {
   const { paths, manifest } = loadManifest(args.moduleDir);
   const issues = [];
   const err = (where, message) => issues.push({ level: "error", where, message });
@@ -37684,6 +37700,19 @@ function moduleValidate(args) {
       );
     }
   }
+  if (cli) {
+    const res = cli(args.moduleDir);
+    if ("unavailable" in res) {
+      warn("cli", `CLI checks skipped, so pack may still fail: ${res.unavailable}`);
+    } else {
+      if (res.report.error) err("cli: package", res.report.error);
+      for (const c of res.report.checks) if (!c.ok) err(`cli: ${c.name}`, c.message ?? "failed");
+      for (const w of res.report.warnings) {
+        const dup = issues.some((i) => i.where === w.where && i.message.includes("toString") && w.message.includes("toString"));
+        if (!dup) warn(w.where, w.message);
+      }
+    }
+  }
   const errors = issues.filter((i) => i.level === "error");
   const warnings = issues.filter((i) => i.level === "warning");
   const clean = errors.length === 0 && warnings.length === 0;
@@ -38216,11 +38245,11 @@ server.registerTool(
   "dforge_module_validate",
   {
     title: "Validate module (offline)",
-    description: "Validate the whole module OFFLINE before packing/installing. Runs every check the per-field tools can't see: dangling FK/reference targets, a missing hidden-FK column, view dataSources/columns pointing at unknown entities/fields, menu dataViewCode \u2192 missing view, role rights on unknown objects, entities with no Select grant, field-spec rules re-run across EVERY field (catching anything that entered via import or a hand edit), toString templates, Formula-vs-Generated set aggregates over virtual child columns, action script files missing from disk, triggers/jobs firing actions that don't exist, DSL static checks, and translation completeness (role labels are install-blocking). Returns errors + warnings in _validate.json. Fix every error BEFORE dforge_module_pack \u2014 it saves a slow pack/install round trip.",
+    description: "Validate the whole module OFFLINE before packing/installing. Runs every check the per-field tools can't see: dangling FK/reference targets, a missing hidden-FK column, view dataSources/columns pointing at unknown entities/fields, menu dataViewCode \u2192 missing view, role rights on unknown objects, entities with no Select grant, field-spec rules re-run across EVERY field (catching anything that entered via import or a hand edit), toString templates, Formula-vs-Generated set aggregates over virtual child columns, action script files missing from disk, triggers/jobs firing actions that don't exist, DSL static checks, translation completeness (role labels are install-blocking), and the CLI's own static checks \u2014 the same set dforge_module_pack runs (errors under 'cli: <check>'). Returns errors + warnings in _validate.json. Fix every error BEFORE dforge_module_pack \u2014 it saves a slow pack/install round trip.",
     inputSchema: moduleValidateSchema,
     annotations: READ_ONLY
   },
-  serialize(moduleValidate)
+  serialize((a) => moduleValidate(a, cliValidate))
 );
 server.registerTool(
   "dforge_module_pack",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.26",
+	"version": "0.2.28",
 	"description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/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",
@@ -35,7 +35,7 @@
 		"install-skills": "node scripts/install-skills.mjs"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.20",
+		"@dforge-core/dforge-cli": "^0.2.22",
 		"@dforge-core/metadata": "^0.0.29",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"

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

@@ -44,6 +44,13 @@ so `IF([completed_date] != null, 100, 0)` gives the same result on the record ca
 a report. At SQL time `=` / `!=` translate to `IS NOT DISTINCT FROM` / `IS DISTINCT FROM`
 to preserve that.
 
+**Text `+` with a NULL side gives NULL**, on the record card and in a report alike:
+`[first_name] + ' ' + [last_name]` is NULL when either name is missing. Wrap a part that may
+be missing — `[first_name] + ' ' + COALESCE([last_name], '')` — or test for it with `IF`.
+The one exception is a formula evaluated for an entity's `toString` (see
+[Computed toString](#computed-tostring)), where a NULL side joins as empty text so a caption
+never goes blank.
+
 ## Examples
 
 ```
@@ -205,7 +212,7 @@ and the JSON shape: `column-types.md` → "Roll-up totals over child rows — us
 [account].[primary_contact].[phone]      -- chained
 ```
 
-Navigation works through `columnType: "R"` columns (reference columns) — every step except the last must be a Reference, and the last reads a field on the final referenced record. Chains of length 1 are **synchronous** and resolved instantly. Chains of length ≥ 2 are **asynchronous** — the formula engine resolves them after the initial data load.
+Navigation works through `columnType: "R"` columns (reference columns) — every step except the last must be a Reference, and the last reads a field on the final referenced record. On the record card and in grids, any navigation — one hop or several — is **asynchronous**: the engine resolves it after the initial data load, from the referenced rows it loads alongside. A formula may navigate back into its own entity (`[parent].[name]` on a self-reference); a formula that reads itself round a loop, directly or through other records, comes back NULL.
 
 **SQL-time (reports, filters, sorts).** Multi-hop navigation works here too: QueryBuilder pre-scans the formula and registers one `LEFT JOIN` per hop, then the translator resolves the path against the final alias. A nav path may also land on a *formula* column of the referenced entity — that formula is translated against the referenced entity's alias, and its own hops are joined off that alias. The same nav map drives formula columns in filters and ORDER BY, so filtering and sorting a report by a nav-formula column works.
 
@@ -222,8 +229,10 @@ Warning wording follows the clause, because the same unresolvable path costs a d
 
 ## Sync vs async formulas
 
-- **Sync formula**: pure local math, no navigation, or one-level navigation that can be JOINed. Evaluated on load and on every edit to a dependency.
-- **Async formula**: multi-hop navigation. Evaluated after the initial data load, re-evaluated when dependencies change.
+- **Sync formula**: no navigation — fields of the same record only. Evaluated on load and on every edit to a dependency.
+- **Async formula**: any navigation (`[ref].[field]`). Evaluated after the initial data load, re-evaluated when a dependency changes — as is every formula that reads it.
+
+At SQL time (reports, filters, sorts, reference display) both kinds are translated to SQL, navigation as `LEFT JOIN`s.
 
 You don't declare which is which — the engine detects it from the formula's AST.
 
@@ -263,6 +272,32 @@ The constraint's `message` (the violation text shown to users) is **localizable*
 }
 ```
 
+### Computed toString
+
+A `toString` placeholder may name a formula column — the way to build a display from more
+than plain fields, e.g. a hierarchy path:
+
+```json
+"toString": "{display_path}",
+"fields": {
+    "display_path": {
+        "columnType": "F",
+        "fieldTypeCd": "text",
+        "baseDatatypeCd": "string",
+        "flags": "V",
+        "formula": "IF([parent_id] = null, [name], [parent].[name] + ' / ' + [name])",
+        "description": "Display Path"
+    }
+}
+```
+
+The formula renders wherever the `toString` does — form caption, reference cells, pickers —
+on the client and in SQL alike. Evaluated for the `toString`, text `+` joins a NULL side as
+empty text, so the caption never goes blank; the same column in a grid or report keeps
+NULL. Test for a missing parent with `IF`, not `COALESCE(a + b, c)`: in the caption `a + b`
+is not NULL when one part is missing, so the fallback never applies. The path is one level
+deep — `[parent].[name]` reads the parent's plain name.
+
 ### Line total (quantity × price)
 
 ```json

package/skills/dforge-module-build/SKILL.md

@@ -80,6 +80,8 @@ Enough to author inline; load the linked reference for the full detail.
   `created_by`/`last_updated_by` with no default — a seeded `audit-full` entity
   must set both to `0` in every record, or use plain `audit`. → `traits`
 - **`toString`** on every entity, `{column}` braces: `"{first_name} {last_name}"`.
+  A computed display (a hierarchy path) goes in a formula column named as the
+  placeholder. → `formulas` (Computed toString)
 - **Data views:** `dataSources` array at root — never a root-level `entityCode` +
   `columns`. Sort is `"order": ["-col", "col"]`. → `data-views`
 - **Menus:** leaf items use `dataViewCode` (not `viewCode`); section nodes omit

package/skills/dforge-module-ship/SKILL.md

@@ -35,6 +35,9 @@ otherwise only surfaces at install:
   don't exist; `[field]` record-context in a job-invoked action
 - **DSL static checks** on every action body
 - **translation completeness** — a missing `roles.<code>.label` fails install
+- **the CLI's static checks** — the same set `dforge_module_pack` runs, reported
+  as `cli: <check name>`. A `cli` warning means they were skipped (CLI missing or
+  too old), so pack can still fail
 
 Read `files["_validate.json"]`. **Every `error` must be fixed** (apply the
 backtrack protocol in `dforge-module-build`) before continuing. Review the