@dforge-core/dforge-mcp 0.2.0 → 0.2.2

package/skills/dforge-mcp-author/references/data-views.md

@@ -67,8 +67,8 @@ If none of an entity's fields are visible (or only its set/child-collection colu
 ```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
+    "code": { "fieldTypeCd": "text", "flags": "EM" },   // E=editable, M=required, but no V
+    "lines": { "columnType": "S", "flags": "VE" }        // visible, but a SET — doesn't count for a grid
 }
 // RIGHT — at least one visible scalar field
 "fields": {

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

@@ -72,7 +72,7 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `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. |
 | `list` | `set` | `S` | Detail list — same 1:N set as `grid`, rendered as a card list instead of a table. |
-| `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`). |
+| `entitylink` | `json` | `D` | Polymorphic link to any entity — stores the **resolved entity id** plus the record's PK (as strings) and a display caption. Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in; pass a qualified entity code (see `action-dsl.md`). |
 
 ## JSON
 

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

@@ -11,26 +11,54 @@ Valid flags regex: `^[VIEMH]*$`
 | `V` | Visible | Column appears in grid / form / card views. Omit to hide from standard UI. |
 | `I` | Internal | Auto-managed by the platform. Used on PK columns, audit timestamps, system fields. Not shown in UI, not directly editable by users. |
 | `E` | Editable | User can modify the value in the UI. Omit for read-only. |
-| `M` | Mandatory | Required (NOT NULL + UI enforcement). |
+| `M` | Mandatory | Required. Resolved into `isNullable: false` at install — see below. |
 | `H` | Hidden | Permanently hidden — never shown, not even in admin metadata views. Stronger than omitting `V`. |
 
 **Only these 5 letters are valid.** The platform rejects any other characters.
 
+## `M` is the platform's one notion of "required"
+
+At install, `MandatoryFlagNormalizer` folds `M` into `isNullable: false` before DDL
+generation. Everything downstream reads only `isNullable`: the `NOT NULL` in the
+generated DDL, `data.insert`'s required-column check, and the red asterisk on the
+client. There is no second signal.
+
+Four consequences worth knowing before you type a flag:
+
+- **`M` makes the column `NOT NULL`.** It is not decoration and not a UI hint. Put it
+  on a column only when a row is genuinely meaningless without the value.
+- **`M` together with `"isNullable": true` is a hard error at pack time**, naming the
+  entity and every offending field. It's a contradiction only you can resolve: drop
+  `M` if the column is optional, or drop `isNullable` if it is required.
+- **`M` is inert on virtual (`R`/`S`/`F`) and identity columns** — nullability is
+  meaningless where there is no physical column. It won't fail, but `VEM` on a
+  Reference over an *optional* FK reads as a required field to the next author, which
+  is exactly how these get out of step. Match the Reference to its FK.
+- **Adding `M` to a shipped field aborts the upgrade** on any tenant whose existing
+  rows leave it empty — rolled back, naming the column and its NULL row count. Give
+  the column a `params.serverDefault` if the install should backfill it. Removing `M`
+  is always safe.
+
+Omitting both `M` and `isNullable` leaves the column nullable — that is the default.
+
 ## Common column flag combinations
 
 | Flags | Meaning | Use case |
 |---|---|---|
-| `"VEM"` | Visible, Editable, Mandatory | Required field shown in UI (most business fields) |
-| `"VE"` | Visible, Editable, optional | Nullable field |
+| `"VEM"` | Visible, Editable, Mandatory | Required field shown in UI |
+| `"VE"` | Visible, Editable, optional | Nullable field — the common case for most business fields |
 | `"V"` | Visible, read-only | Display-only, like formula columns or computed values |
-| `"EM"` | Editable, Mandatory, **not visible** | Hidden FK columns in the FK+Reference pattern |
+| `"E"` | Editable, **not visible** | Hidden FK column of an *optional* relation |
+| `"EM"` | Editable, Mandatory, **not visible** | Hidden FK column of a *required* relation |
 | `"I"` | Internal | Trait-provided columns (PK, audit timestamps). Platform-managed. |
 | `""` (empty) | No flags | Rare — column exists but is invisible and not editable |
 
 ## Rules
 
-1. **Hidden FK columns**: always `"EM"`. They must be writeable (E) and required (M), but never shown (no V).
-2. **Visible Reference columns**: always `"VEM"`. The user sees and edits the lookup picker.
+1. **Hidden FK columns**: `"E"`, or `"EM"` when the relationship is genuinely required.
+   Writeable (E), never shown (no V). `M` here is what makes the FK `NOT NULL`.
+2. **Visible Reference columns**: `"VE"`, or `"VEM"` when the FK is required — **keep the
+   two halves in step**. `dforge_entity_reference_add({ required })` sets both for you.
 3. **Formula columns**: usually `"V"` (visible, read-only). The user never edits them.
 4. **Trait columns** (PK, audit): use `"I"` (internal). These are set automatically by `traits: ["identity", "audit"]`.
 5. **Don't use `I` on your own columns** — it's reserved for trait-provided and platform-managed columns.
@@ -68,6 +96,9 @@ These are **NOT** flag letters. They're separate properties on the column defini
 - Using `"U"` for unique — **not a valid flag**. Use `"isUnique": true` or indexes.
 - Using `"S"` for searchable — **not a valid flag**.
 - Using `"P"` for primary key — **not a valid flag**. Use `"isPk": true` or the `identity` trait.
+- Declaring `M` **and** `"isNullable": true` on the same field — a contradiction that fails the pack.
+- Reaching for `"VEM"` by default — `M` now means `NOT NULL`. Most business fields are `"VE"`.
+- Putting `M` on a Reference whose hidden FK is optional — inert, but it misreports the field as required.
 - Using `"VEM"` on trait-provided columns (PK, audit) — **don't**. Traits set their own flags (`"I"`).
 - Using `"I"` on business columns — **don't**. `I` means "platform-managed"; regular business columns use `V`/`E`/`M`.
 - Using long names like `"Visible,Editable"` — **wrong**. Single letters concatenated: `"VE"`.

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

@@ -26,6 +26,12 @@ The same grammar applies everywhere.
 `CONTAINS` / `STARTS_WITH` / `ENDS_WITH` are infix operators, not functions — write
 `[note] CONTAINS 'urgent'`, never `CONTAINS([note], 'urgent')`.
 
+**Comparison is null-safe and two-valued in every context.** `null = null` is true, and
+`[x] != null` is true for any non-null `x`. There is no SQL-style third "unknown" answer,
+so `IF([completed_date] != null, 100, 0)` gives the same result on the record card and in
+a report. At SQL time `=` / `!=` translate to `IS NOT DISTINCT FROM` / `IS DISTINCT FROM`
+to preserve that.
+
 ## Examples
 
 ```
@@ -156,8 +162,9 @@ like any other boolean. A bare `date` column is treated as a **local calendar da
 - `AVG`, `MIN`, `MAX` similarly
 
 > ⚠️ **Set aggregation is NOT a Formula (`F`) feature.** `SUM([set].[field])` in an `F` column is
-> unsupported by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and nav resolution
-> only walks single-hop N:1 references, never a 1:N set. It silently renders **empty** (no error).
+> unsupported by **either** engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and nav
+> resolution walks N:1 references only, never a 1:N set, however many hops it is given. It
+> silently renders **empty** (no error).
 
 Put set aggregations in a **Generated (`G`) column** instead. The installer detects the set
 navigation and maintains the value with a database trigger on the child table. The aggregated
@@ -186,9 +193,20 @@ 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). 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. 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.
+
+**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.
+
+Hops are counted from the query's **root** entity and capped at `MaxNavigationDepth`, whether they come from a dotted column, a formula's own navigation, or the combination — so the hops spent reaching a formula reduce the budget left for that formula's own navigation.
+
+Still unavailable at SQL time — the column comes back NULL and the **response carries a warning** naming the column and the reason:
+
+- Settings references `$[SettingName]`
+- Navigation past the hop cap
+- **Extension-table columns** — a column an extension module added lives in a separate 1:1 ext table needing its own JOIN, and every alias the translator emits is the entity's own base alias. Applies to the hidden FK and to the Reference built on it, on the query's own entity as well as a referenced one
+- **Misauthored nav paths** — a final segment that isn't a column of the referenced entity, or a dot after something that isn't a Reference (`account.account_name.foo`)
 
-**SQL-time (reports, filters, sorts):** single-hop navigation (`[ref].[field]`) is translated to a `LEFT JOIN` and computes in reports and query datasets. Multi-hop chains and `$[Setting]` references are **not** available at SQL time — the column returns NULL there and the response carries a warning naming the column. Keep report-bound formulas to single-hop navigation.
+Warning wording follows the clause, because the same unresolvable path costs a different thing in each: a SELECT slot goes NULL (*"could not be computed and will be empty"*), an ORDER BY term is dropped so rows come back in a different order (*"Sorting by … was skipped"*), and a WHERE condition is dropped so **more** rows come back than were asked for (*"Filter on … was ignored"*). Untranslatable formula filters are never dropped silently.
 
 ## Sync vs async formulas
 

package/skills/dforge-mcp-author/references/schema-import.md

@@ -79,8 +79,10 @@ If the source uses non-standard audit column names (e.g. `date_created`, `modifi
 
 For each FK, create **two columns** following the FK+Reference pattern:
 
-1. Hidden FK column: `flags: "EM"`, matching `dbDatatype`
-2. Visible Reference column: `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VEM"`, with `link`
+1. Hidden FK column: `flags: "E"` — `"EM"` only when the source column is `NOT NULL` — matching `dbDatatype`
+2. Visible Reference column: `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags` **matching the FK** (`"VE"` / `"VEM"`), with `link`
+
+`M` resolves to `isNullable: false` at install, so carrying it onto an FK the source declares nullable would import the column as `NOT NULL`. `dforge_dbml_import` / `dforge_module_import` take `M` from the source's own nullability.
 
 Plus declare the constraint in the entity's `references` block.
 

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

@@ -42,8 +42,9 @@ For each entity:
 ### FK+Reference pattern
 
 - [ ] Every reference column (`columnType: "R"`) has a paired hidden FK column
-- [ ] The hidden FK column has `flags: "EM"` (not `V`, not `I`)
-- [ ] The reference column has `flags: "VEM"`, `fieldTypeCd: "lookup"`, and a `link` object
+- [ ] The hidden FK column has `flags: "E"` — `"EM"` only if the relation is required (not `V`, not `I`)
+- [ ] The reference column has `flags` **matching the FK** (`"VE"` / `"VEM"`), `fieldTypeCd: "lookup"`, and a `link` object
+- [ ] No field declares `M` together with `"isNullable": true` — that combination fails the pack
 - [ ] `link.entity` points to an entity that exists (in this module or a dependency)
 - [ ] `link.thisKey` matches the FK column name on this entity
 - [ ] `link.otherKey` matches the PK column name on the target entity

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

@@ -57,8 +57,10 @@ Enough to author inline; load the linked reference for the full detail.
 - **A relation is TWO columns + a references entry.** Use
   `dforge_entity_reference_add` — it emits all three parts. → `column-types`
 - **Flags** are letters from `V I E M H` only (never `U`/`S`/`P`): `VEM`
-  required+visible, `VE` optional+visible, `V` read-only, `EM` hidden FK, `I`
-  trait-provided. → `flags`
+  required+visible, `VE` optional+visible, `V` read-only, `E`/`EM` hidden FK
+  (optional/required), `I` trait-provided. `M` means required — it resolves to
+  `isNullable: false`, so it makes the column `NOT NULL`; don't spend it as
+  decoration, and never pair it with `"isNullable": true`. → `flags`
 - **`fieldTypeCd` = UI control; `dbDatatype` = SQL type.** Omit `dbDatatype` on
   plain data columns — it's derived. Set it only for a hidden FK or to override
   size/precision. Common fixes: `number` not `integer`/`float`; `phone` not
@@ -168,9 +170,14 @@ to fill a sub-step** — a pure CRUD module skips Phase 2 entirely (record it wi
 | 2c Jobs | a cron timer fires | `dforge_job_add` |
 | 2d Webhooks | a DB event → outbound POST | `dforge_webhook_add` |
 
-**2a Actions.** Load all four resources in the action row — the wrong-field-
-access / wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only
-surface when you cross-check them. Draft the DSL, run
+**2a Actions.** First check the action is an action at all: it must **change**
+something. If the `execute:` block would only read, compute and `info()` the
+answer, build a report, a formula column, or an action that writes a result
+record instead — a printed number is never stored and can't be re-read
+(`dforge://reference/action-dsl`, *When an action is the wrong tool*). Then load
+all four resources in the action row — the wrong-field-access /
+wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only surface when
+you cross-check them. Draft the DSL, run
 **`dforge_action_check({ dslBody, executionMode })`** to catch install failures
 before committing, then `dforge_action_add`. One action per turn.