@dforge-core/dforge-mcp 0.2.4 → 0.2.14

package/CHANGELOG.md

@@ -4,6 +4,189 @@ 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.6
+
+Record reports — a report attached to an entity so it opens **from a record**, with the
+record's values feeding its parameters — plus a report-level home for report parameters,
+and the removal of two parameter spellings the installer never read.
+
+Requires `@dforge-core/metadata` ≥ 0.0.15 (bumped): the vendored
+`resources/schemas/reports.schema.json` served as `dforge://schema/reports` comes from
+there.
+
+### Added — record-report attachments
+
+A report in `ui/reports.json` gains an `entities` array. Each entry attaches the report to
+one entity, mapping report parameters to source columns on it:
+
+```jsonc
+"credit_check": {
+    "entities": [
+        { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 },
+        { "entityCd": "crm.quote",     "params": { "customer_id": "customer_id" }, "orderNum": 45 }
+    ]
+}
+```
+
+The report then appears on that record's toolbar and opens on a record-scoped route with
+the mapped params resolved server-side and hidden. `dforge_report_add` accepts and
+documents the block; `references/reports.md` gains a **Record reports** section with the
+rules (source-column allowlist, type compatibility, one attachment per (entity, report)
+pair, the `"metadata": ">=1.5.0"` gate, and the cross-module dependency bound).
+
+Note the two different `params` keys, which the tool description now calls out: on an
+attachment it is the *mapping* (param code → column); on the report or a dataset it is the
+*declaration*.
+
+### Added — `dforge_module_validate` checks reports
+
+Mirrors the server's new pack-time `ReportAttachmentValidator`, so these fail offline
+instead of at install against a live tenant:
+
+- a mapped param code neither the report-level `parameters` block nor any dataset declares;
+- a source column the entity doesn't have, or one that's a set / formula / free-text column;
+- two attachments to the same entity in one report (the second overwrites the first);
+- an attachment to a cross-module entity whose module isn't a declared dependency;
+- `isRequired`, a top-level `link`, or `fieldTypeCd` + `domain` together on a param;
+- a warning when a module ships attachments with no `metadata` dependency.
+
+### Added — report-level `parameters`
+
+Report parameters are **report-scoped**: the declaration is stored once per report
+(`report.param_set_id` → `param_set`), the authoring API is `report.params.save`, and
+`report.get` flattens per-dataset defaults report-wide before use. The installer had only
+ever read the per-dataset shorthand, so a report-level block was silently dropped and the
+report installed with no parameters at all — which is what made
+`crm-fin.customer_statement` and `wms-fin.vendor_statement` ship parameterless.
+
+Both declaration sites are now legal and mean the same thing; the installer merges them,
+**report level winning** on a code collision:
+
+```jsonc
+"customer_statement": {
+    "parameters": {
+        "customer_id": { "label": "Customer", "fieldTypeCd": "lookup",
+                         "params": { "link": { "entity": "parties.party" } }, "required": true }
+    },
+    "datasets": { "statement_invoices": { }, "statement_payments": { } }
+}
+```
+
+Declare at report level when several datasets use the parameter — `customer_statement` is
+exactly that case, and there is no meaningful dataset to attribute it to.
+`datasets.<cd>.params` stays the right shorthand for a single-dataset parameter, and every
+module written before this keeps working.
+
+`dforge_module_validate` merges both sites when resolving a record-report mapping, so a
+mapping onto a report-level parameter resolves exactly as install will resolve it.
+
+### Fixed — two report-param spellings that are silently ignored
+
+Unlike `parameters`, these are simply misspellings of keys that already exist, so they are
+gone from the schema rather than implemented — and the validator flags them at either
+declaration site:
+
+- **`isRequired`** — the key is `required`; the parameter installed as optional.
+- **top-level `link`** on a lookup parameter — it belongs under `params`; the parameter
+  installed with no autocomplete.
+
+`references/reports.md` also corrects the rights-key example from `report.<code>` to the
+colon form `report:<code>`, and the lookup parameter config from `params.entityCd` to
+`params.link.entity`.
+
+### Changed — steer calculation toward reports, not the DSL
+
+`action-dsl.md`'s *When an action is the wrong tool* now names the record report as the
+direct replacement for a `check_…` action — same toolbar entry point, but the user sees
+the open invoices and the ageing rather than just "FAILED" — and adds the general rule:
+**do not compute in the DSL what a report dataset already aggregates.** Sums, ratios,
+ageing buckets and exposure get formatting, drill-through, row caps and live re-reads for
+free from a report; DSL arithmetic over `select()` reproduces that badly, once, somewhere
+nothing else can reuse. Write DSL when the number must be *written down* or must *stop*
+something. The same steer is in `dsl-reference.md`, Phase 2a and Phase 3c of the
+`dforge-module-build` skill, and the validation checklist.
+
+## 0.2.5
+
+Catches up with the platform's parameter-options work (dForge-core 1.20.0). A dropdown
+parameter can now carry real labels, and — better — borrow the shared list its target
+column already uses. Both were undocumented here, and one reference actively said the
+first was impossible.
+
+### Changed — `translations.md` said param option labels didn't exist
+
+The section table listed `actions` / `reports` params as translating `{ label }` and
+nothing else, which was accurate when written: parameters had no schema location for a
+per-choice label at all. An author who followed it concluded — correctly, at the time —
+that a dropdown param showing `bank_transfer` instead of "Bank transfer" was unfixable.
+The platform added the slot, so the table now shows
+`params: { param_cd: { label, options: { value: … } } }` for both sections, and a new
+**"Action / report PARAM option labels ARE translatable"** section documents the
+value-keyed, partial-override shape (identical to field options) plus the two things that
+trip authors up: base labels must exist in the DSL first, and a domain-backed param
+shouldn't be translated here at all.
+
+### Added — `domain <domainCd>` param form
+
+`action-dsl.md` and `dsl-reference.md` gain the parameter form that borrows a column
+domain:
+
+```
+params:
+    payment_method: domain payment_method required "Payment method for this batch"
+    status:         domain fin.doc_status optional "Status"
+```
+
+Both now lead with it and frame inline `options=` as the narrow case. The reason is
+duplication, not typing: a param whose value gets written to a domain-backed column used
+to restate that column's enum, so the same list was authored twice, translated twice, and
+free to drift — and a param option whose code isn't on the column is a value the grid
+can't label. `column-domains.md` gains a matching **"Using a domain in an action / report
+param"** section, and `reports.md` documents the JSON equivalent
+(`{"domain": "fin.doc_status"}`, mutually exclusive with `fieldTypeCd`).
+
+Also documented: the param keeps its **own** caption (only the choices come from the
+domain), install materializes just the domain's `fieldTypeCd` (a parameter has no
+storage, so datatype and sizing don't apply), and nothing may follow the description —
+`options=`, `min=` and friends are a compile error there, the same authority rule columns
+already had.
+
+### Changed — labeled `options=` in the DSL references
+
+The dropdown row in `dsl-reference.md` showed only `options=low,medium,high`, which is
+exactly the shape that renders raw codes in every locale. It now shows the labeled forms
+(`options=[low:Low, medium:Medium, high:High]`, and the JSON object form for icon/colour),
+with the wrapping rule spelled out: the trailing `key=value` scan is whitespace-delimited,
+so a label containing a space needs `[ ]` or quotes around the list.
+
+`resources/docs/conventions.md` (vendored from dForge-core) gains the same guidance
+inline. It was **not** re-synced wholesale: the vendored copy has diverged *forward* from
+core in ~15 places — seed-data `cuid`-is-int8 warnings, mandatory-flag `M` semantics,
+rights characters — so a straight `cp` (what `VENDOR_REFS=1` does) would silently drop
+them. That drift is worth reconciling deliberately, in its own pass.
+
+### Fixed — `dforge_module_validate` rejected a domain-backed report param
+
+`resources/schemas/reports.schema.json` required `fieldTypeCd` and had no `domain` key, so
+the very form the docs above now recommend failed validation. `@dforge-core/metadata` is
+bumped to `^0.0.14` and the 16 vendored schemas re-synced, which lands the new `paramDef`:
+`domain` is accepted (`domain_cd` or `module_cd.domain_cd`), `fieldTypeCd` is no longer
+required — a param declaring neither installs as `text` — and the one rejected combination
+is declaring both. Action params were never affected (the DSL has no JSON schema).
+
+### Changed — dependency bumps
+
+`@dforge-core/dforge-cli` `^0.2.12` → `^0.2.13`, `@dforge-core/metadata` `^0.0.13` →
+`^0.0.14`, and the dev toolchain moves to `vitest` 4 and `@types/node` 26. A
+`pnpm-workspace.yaml` pins the pnpm build allowlist and exempts the freshly-published
+dForge packages from `minimumReleaseAge`, which otherwise blocks installing them the day
+they ship.
+
+### Known gap
+
+`dforge_translation_sync` doesn't seed `options` maps for fields, domains or params —
+authors write those keys by hand.
+
 ## 0.2.3
 
 Catches up with the platform's current-user work: `currentUserId()` exists now,