@dforge-core/dforge-mcp 0.2.45 → 0.2.47

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

@@ -118,8 +118,8 @@ See [flags.md](flags.md) for the flag string, [column-types.md](column-types.md)
 
 | `viewType` | Description | `viewConfig` | When to use |
 |---|---|---|---|
-| `grid` | Spreadsheet-style table with sortable columns | — | Default for most entities; bulk data |
-| `list` | Compact list view | — | Mobile-friendly, card-sized items |
+| `grid` | Spreadsheet-style table with sortable columns | `groupByField`, `groupByOptions`, `collapsedGroups` (all optional) | Default for most entities; bulk data |
+| `list` | Compact list view | `groupByField`, `groupByOptions`, `collapsedGroups`, `inlineAdd`, `levels` (all optional) | Mobile-friendly, card-sized items |
 | `kanban` | Columns grouped by a status field | `groupByField` | Workflow entities with stages (deals, tickets) |
 | `gallery` | Image-forward card grid | — | Image-heavy entities (products, real estate) |
 | `tree-grid` | Hierarchical grid with expand/collapse | — | Tree structures (folders, categories, org charts) |
@@ -151,6 +151,42 @@ Some view types need additional configuration via the `viewConfig` property:
 
 `groupByField` — the dropdown/status column to group cards by. Each distinct value becomes a kanban column.
 
+### Grid and list grouping
+
+A `grid` or `list` view can ship a default grouping. Rows split under a header per value (colour or icon, label, count),
+and a header click folds its group away. Every key is optional; without them the view is ungrouped.
+
+```json
+{
+    "tickets_grid": {
+        "viewType": "grid",
+        "label": "Tickets",
+        "dataSources": [{
+            "entityCode": "ticket",
+            "columns": ["subject", "status", "priority", "assignee_id"]
+        }],
+        "viewConfig": {
+            "groupByField": "status",
+            "groupByOptions": ["status", "priority", "assignee_id"],
+            "collapsedGroups": ["closed"]
+        }
+    }
+}
+```
+
+- `groupByField`: the column the rows are grouped by. It must be a dropdown, flags, reference (`columnType: "R"`) or
+  `user` column.
+- `groupByOptions`: the columns the Group menu offers. Each follows the same rule, and the list must include
+  `groupByField`. Leave it out to offer every groupable column.
+- `collapsedGroups`: values of `groupByField` whose groups start folded. It needs a valid `groupByField`, and for a
+  dropdown each entry must be one of its option values.
+- `inlineAdd` (`list` only): an add row in each group, or at the top when ungrouped.
+
+The install refuses a view that breaks these rules, and `dforge_module_validate` reports it first. The default is a
+single level. A user can stack more levels (priority, then status) from the gear menu; that choice lives in their
+session, not in the module. A grouped grid loads up to 2,000 rows instead of paging and warns past that. Needs platform
+1.28.11.
+
 ### Calendar
 
 ```json

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

@@ -142,11 +142,42 @@ The whole date family evaluates identically **client-side and SQL-time** (report
   `'bool'`/`'boolean'`, `'date'`, `'datetime'`/`'timestamp'`/`'timestamptz'`
 - `CURRENT_USER_ID()` — the id of the requesting user
 
+### Register functions
+
+- `SLICE('module.register', 'resource', date, 'dimension', value, …)` — an information
+  register's value in effect on `date` (1C `СрезПоследних`): the resource of the newest record
+  at or before the date whose dimensions equal the values, null when none is. The register,
+  resource and dimension names are text literals; the date and the values are expressions over
+  the row, so a document line reads its price on its document's date:
+  `SLICE('pricing.item_price', 'price', [doc].[doc_date], 'item_id', [item_id], 'price_type_id', [doc].[price_type_id])`.
+  Every dimension must be given; a register without `period` takes `null` as the date.
+  - **Computed by the database only** — in a print form, a report, and `data.get` naming the
+    column. The browser does not recompute it on edit; it keeps the value the server loaded.
+  - Read with the user's rights on the register's records: Select in the folder, the folder's
+    row filter, the resource and every dimension column visible in the folder's view. Otherwise
+    the cell is empty and the response carries a warning. That includes a row filter over the
+    records that cannot be applied (a dotted path or an extension column): the `SLICE()` comes
+    back empty with a warning instead of failing the whole query.
+  - Install refuses a register that is not an `info` register of this module or of a
+    dependency (a register of another kind "has no slice"), an unknown resource or dimension, a
+    missing dimension, and a literal `null` as a dimension value or as the date of a register
+    that declares a `period` (it matches no record). A `null` that only appears at runtime, such
+    as a line with an empty price type, still gives an empty cell, with no warning.
+    `dforge_module_validate` and `dforge_module_pack` (the CLI's static checks) catch only a
+    malformed call, such as a name that is not a text literal or a dimension without its value;
+    whether the register, resource and dimensions exist is known at install.
+  - Refused at install in a `G` column: it is computed when a row is written and would not
+    follow a record added to the register later. Use an `F` column.
+  - Newest record only: there is no `first` mode as `getSlice` has. Each row is one index
+    descent of the register's `(dimensions, period)` index, which the platform creates.
+  - The date is compared as `period <= date`: against a `timestamp` period, a date-only
+    document date is midnight, so a record later that day is not in the slice.
+
 ### Client-side vs SQL-time evaluation
 
 An `F` column is evaluated **client-side** in grids and cards, but translated to **SQL** when a
 report selects it, or when it is used in a filter or sort. **Every function listed here is
-implemented in both**, so a column reads the same in a grid and in a report; a test executes
+implemented in both** — except `SLICE()`, which only the database computes — so a column reads the same in a grid and in a report; a test executes
 each one against PostgreSQL and diffs the result against the client runtime.
 
 Four deliberate points of agreement, because the engines disagree by nature:

package/skills/dforge-mcp-author/references/print-templates.md

@@ -73,7 +73,9 @@ A printed set, nested or not, needs **Select** on its entity in the folder, as `
 
 A currency column prints its glyph for the common codes (`EUR` → `€`, `USD` → `$`, `GBP` → `£`, `UAH` → `₴`, `PLN` → `zł`); other codes print as the code. `format_currency` follows the same mapping.
 
-Formula columns (`F`) are read in the same SQL as the record, as `data.get` does, so a formula that navigates references or calls a SQL function prints what the grid shows, and `TODAY()` / `NOW()` work. A formula the SQL translator cannot express prints empty and the response carries a warning naming the column.
+Formula columns (`F`) are read in the same SQL as the record, as `data.get` does, so a formula that navigates references prints what the grid shows, and `TODAY()` / `NOW()` work. A formula uses the built-in formula functions only: it cannot call a module's SQL function. A formula the SQL translator cannot express, or one reading what the user may not read, prints empty, and `print.render` / `print.renderPdf` return it in `warnings` (a line column's prefixed with its set's name); the card's PDF button shows them.
+
+A value that changes over time — a price, an employee's position, an organization's code — lives in an information register: print it as it stood on the document's date with a `SLICE()` formula column on the line or the document (see formulas.md). Each line reads its own value in the query that loads the set.
 
 **Sets: loading and order.** A set is loaded when the template's Liquid code (`{% … %}` or `{{ … }}`) mentions its name anywhere: a `for`, a filter, a condition, `.size`, `.first`. Plain text, `{% comment %}` / `{% raw %}` blocks, string literals and the member of a path (`rec.lines`) do not count, and a snippet's code is not scanned (mention the set in the host template). Rows come in primary-key order; sort in the template:
 
@@ -85,6 +87,21 @@ Formula columns (`F`) are read in the same SQL as the record, as `data.get` does
 
 `sort` takes a column code and sorts the value as the template sees it (a dropdown or reference sorts by its label). Text order follows the engine, not the database collation. `{# … #}` after an expression in examples is a note for the reader, not syntax: write a real comment as `{% comment %} … {% endcomment %}`.
 
+## Computed values and grouped rows
+
+| The form needs | Do |
+| --- | --- |
+| A value of the record or of a record it references (the organization's requisites as one block) | An `F` column on the entity: references and built-in functions |
+| A value per line (places, weight through the product's units) | An `F` column on the line entity, printed as `line.<col>` |
+| One total over a set | Over a stored line column (`D`, or a `G` on the line): a `G` column on the document (`SUM([lines].[amount])`). Over a line `F` column: a `plus` accumulator in the loop, `{% assign s = 0 %}{% for l in lines %}{% assign s = s \| plus: l.places %}{% endfor %}`, since a `G` cannot sum an `F` child (install fails with `column old.<field> does not exist`) |
+| Lines grouped by a column, totals per group (by product and series, by VAT rate, a packing list by pallet) | **Not available in the print context yet.** It prints the record and its sets as stored |
+
+For the last row, do not work around it:
+
+- **Not in Liquid filters.** `where`, `sum`, `group_by` and `where_exp` run in the LiquidJS preview, but Scriban (the print) fails with "The function `where` was not found". Filter and total with `{% if %}` and `plus` inside a `for`, which both engines run.
+- **Not a print table filled by an action.** It stores a copy of the document that drifts from it.
+- **Not a stored procedure.** The grouping itself is a grouped query (`references/queries.md`): `group` on the column, `sum` over a line `F` column.
+
 ## Custom filters
 
 | Filter                                          | Example                                                | Output                       |
@@ -113,7 +130,7 @@ Full mechanics + an EPC SEPA QR worked example: [`docs/ui/print-qr-codes.md`](..
 
 ### Amount in words
 
-The platform has no number-to-words filter. The `common-words` module (`modules/common-words`, a dependency to declare) ships snippets that write an amount or a plain quantity out in Ukrainian, English or German. Set the inputs, then include:
+The platform has no number-to-words filter. The `common-words` module (`modules/common-words`, a dependency to declare) ships snippets that write an amount or a plain quantity out in Ukrainian, Russian, English or German. Set the inputs, then include:
 
 ```liquid
 {% assign words_amount = total %}
@@ -122,9 +139,17 @@ The platform has no number-to-words filter. The `common-words` module (`modules/
 {% include 'common-words.money' %}
 ```
 
-1234.56 EUR prints «eintausendzweihundertvierunddreißig Euro 56 Cent». `words_amount` must be a numeric field, not text. `words_currency` is an ISO 4217 code in any case; an unlisted currency prints its code. `words_lang` is `uk` (default), `en` or `de`; an unknown code prints `[common-words: unknown language xx]`. `words_cap = true` capitalises the first letter. `common-words.money` only picks the language; `money_uk` / `money_en` / `money_de` can be included directly, and `common-words.quantity` writes a count of things («двадцять одна штука», «twenty-one pieces»): `words_number` (numeric, a fraction rounds half up), optional `words_unit` (forms joined by `|`: three for Ukrainian, two for English and German) and `words_gender` (`m` / `f` / `n`), plus `words_lang` and `words_cap` as above. The text lives in the module, so a fix or a new currency is a module update; a new language is a new `money_xx.html` plus a line in `money.html`.
+1234.56 EUR prints «eintausendzweihundertvierunddreißig Euro 56 Cent». `words_amount` must be a numeric field, not text. `words_currency` is an ISO 4217 code in any case; an unlisted currency prints its code. `words_lang` is `uk` (default), `ru`, `en` or `de`; an unknown code prints `[common-words: unknown language xx]`. `words_cap = true` capitalises the first letter. `common-words.money` only picks the language; `money_uk` / `money_ru` / `money_en` / `money_de` can be included directly, and `common-words.quantity` writes a count of things («двадцять одна штука», «twenty-one pieces»): `words_number` (numeric, a fraction rounds half up), optional `words_unit` (forms joined by `|`: three for Ukrainian and Russian, two for English and German) and `words_gender` (`m` / `f` / `n`), plus `words_lang` and `words_cap` as above; `quantity_uk` / `quantity_ru` can be included directly too. The text lives in the module, so a fix or a new currency is a module update; a new language is a new `money_xx.html` plus a line in `money.html`.
+
+`quantity_uk` and `quantity_ru` also write a fraction in words. With `words_minor` + `words_minor_digits` (1–6) the fraction gets its own unit, as 1C's ЧислоПрописью does for a weight: «одна тысяча двести пятьдесят кг. пятьсот г.» (a zero fraction prints «ноль г.»). With `words_decimal = true` the number is a decimal fraction up to three digits, trailing zeros dropped: «двадцять одна ціла дванадцять сотих тонни». The unit comes in the 2–4 form, or as `words_unit_fraction` ('кілограма' for a Ukrainian masculine unit). The grammar is correct where 1C's is not: 1.001 is «одна ціла одна тисячна». English and German take neither input.
+
+Snippets run on Scriban (print) and LiquidJS (preview), so write them for both:
 
-Snippets run on Scriban (print) and LiquidJS (preview), so write them for both: no `floor` on big numbers, no number taken from `split` / `slice`, plain `{% comment %}` without trim dashes.
+- No `floor` on big numbers: Scriban's goes through a double and rounds them up.
+- No `modulo: 1` on a fraction without snapping the whole part with `round`. LiquidJS 10.30 leaves float noise: `0.44 | modulo: 1` is 0.43999999999999995.
+- Round a fraction half up on its decimal digits, read from the number's text (`append: ''`; the server may print a comma; a browser double under 1e-6 prints as `5e-7`), never by `times` / `plus: 0.5` / `floor`. A double's text is the shortest decimal it stands for, so this matches the server's decimals both on a tie (960.015 → 02) and just below one (1000000000.0049999 → 00). No epsilon can do both.
+- No number taken from `split` / `slice`. A digit is read as `'x0123456789' | split: ch | first | size | minus: 1`.
+- Plain `{% comment %}` without trim dashes.
 
 ## Module package layout
 
@@ -187,7 +212,7 @@ my_module/
 - **Writing an amount in words by hand.** Include `common-words.money` instead of a custom filter or lookup table.
 - **Module-installed template renamed in editor.** The editor preserves the original `template_cd` so `{% include %}` references stay intact — don't try to work around it.
 
-Module-installed print-template rows can't be deleted from the editor — uninstall the owning module to remove them.
+Module-installed print-template rows can't be deleted from the editor. A template or snippet the package no longer declares is deleted on upgrade (dropped from `print_templates.json`, moved to another entity, or the file gone entirely); tenant-authored rows are never touched. To retire a template, remove it from the package, and remove or repoint any scheduled print subscription that names it: nothing references a template by key, so the subscription is not blocked, and its next run fails and suspends it.
 
 ## Reference
 

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

@@ -12,7 +12,8 @@ Lives in: `ui/queries.json`
 | Simple aggregation — "totals by X" | **Pre-built query** (`ui/queries.json`) |
 | Ad-hoc exploration by the user | **Query Builder** (runtime, no module authoring needed) |
 | Complex multi-dataset visualizations with charts/KPIs | **Report** (`ui/reports.json`) |
-| Full SQL with window functions, CTEs, cross-schema | **Report with stored procedure** |
+| Totals grouped by a reference, or summing a value computed per row (lines by product, totals by VAT rate) | **Pre-built query**: `group` on the reference, `sum` over an `F` column of the entity (see *Calculated columns*) |
+| Full SQL with window functions, CTEs, cross-schema, or a formula over an aggregate (`CEIL(SUM(qty) / box)`) | **Report with stored procedure** |
 
 Queries fill the gap between views (flat, no aggregation) and reports (heavy, need layout config).
 
@@ -131,6 +132,17 @@ Columns can traverse references up to 2 levels deep:
 
 The query engine automatically JOINs the referenced entities.
 
+A reference path can be grouped or aggregated like any column: `{ "c": "product.unit", "agg": "group" }`.
+
+### Calculated columns
+
+A value computed per row is aggregated in two ways:
+
+- **An `F` column of the entity**, named by its code: `{ "c": "places", "agg": "sum" }`. Its formula may navigate references (`[qty] / [product].[box_qty]`). This is the way for anything that reads another entity.
+- **An ad-hoc formula** in the query: `{ "formula": "[qty] * [price]", "agg": "sum", "alias": "amount" }`. It reads the root entity's own columns only: a navigation path fails the request.
+
+The aggregate is applied to the row value, `SUM(formula)`. A formula over the aggregate (`SUM([a]) / COUNT([a])`, `CEIL(SUM([qty]) / [box_qty])`) is not expressible: in grouped mode a column without `agg` is dropped, and `SUM` / `COUNT` are not formula functions. That needs a stored procedure. The query is grouped when at least one column, plain or formula, has `agg: "group"`; there is no `grouping` switch. Aggregates without a `group` column are not a grand total: the request runs as an ungrouped row query and the aggregates are ignored, with no error.
+
 ### Filters
 
 Filters use the standard JSON filter format (see `references/filters.md`): `{ "c": column, "o": operator, "v": value }`.
@@ -306,7 +318,10 @@ Query names and descriptions are translated in each non-English `translations/<l
 
 - Putting SQL in the `query` object — **wrong**. Queries use the JSON format, not raw SQL. For raw SQL, use stored procedures in reports.
 - Using `"column"` instead of `"c"` in columns/filters — **wrong**. Use the short keys.
-- Forgetting `"agg"` on columns in grouped mode — every column needs an aggregation assignment.
+- Forgetting `"agg"` on columns in grouped mode — a column without one is dropped from the result.
+- Only aggregates, no `group` column, expecting one total row — **runs ungrouped**, the aggregates ignored and no error. Group by a constant-valued column, or total in a `G` column or a report.
+- Writing a stored procedure to group lines and sum them — **wrong tool**. Grouping by a reference and summing an `F` column is a grouped query, and it runs under the user's entity, column and row-level security, which a stored procedure bypasses. Reach for SQL only for what the JSON cannot say (a formula over an aggregate, window functions, CTEs).
+- Navigating a reference inside an ad-hoc `formula` (`[product].[box_qty]`) — **fails**. Declare an `F` column on the entity and aggregate it by code.
 - Referencing columns from unrelated entities — queries can only traverse the root entity's references.
 - Using `@TODAY`, `@CURRENT_USER`, or any `@placeholder` syntax in filter values — **wrong**. Queries do not support parameter substitution. Use the function operator instead: `{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }`.
 - Using a function as the value of a comparison operator (`<`, `>`, `=`, `!=`, `between`) — **wrong**. Functions are standalone conditions, valid only with `"o": "f"` (full detail + examples under "Dynamic date and user filters" above). `{ "c": "due_date", "o": "<", "v": { "fn": "isToday" } }` is invalid; use `{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }`.

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

@@ -256,6 +256,7 @@ execute:
 ```
 
 - A dimension left out is summed over by `getBalance` and `getTurnover`. `getSlice` refuses an omitted dimension.
+- `getSlice` answers one dimension tuple from an action. A value per row — each line's price on its document's date, in a print form, report or view — is the formula `SLICE()` on an `F` column (formulas.md).
 - As-of reads and `getTurnover` need a journal with both stamps.
 - A read of the wrong kind is refused, naming the right one.
 - DSL reads are gated by the action's Execute right, not Select on the register tables.

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

@@ -75,7 +75,7 @@ A report has a `label`, a `description`, a `datasets` map, a `layout` object (`{
 ```
 
 - `query.entityCd` — source entity code (**not** `entityCode`).
-- `query.columns` — column codes; supports dot navigation (`customer.name`).
+- `query.columns` — column codes; supports dot navigation (`customer.name`). Plain column codes and reference paths only: an `{ "c", "agg" }` or `{ "formula" }` object fails `report.run`. Grouping and ad-hoc formulas belong to `ui/queries.json`; in a report, aggregate in the visualization.
 - `query.filter` — canonical filter (`{c,o,v}` or `{g,i:[...]}`); use `@param_code` to reference a parameter.
 - `query.sort` — `[{ c, d }]` where `d` ∈ `asc | desc`.
 - `columnsDef` — optional per-column display overrides (`{ label, fieldTypeCd, format, width }`; each key replaces the projected value). `label` is a literal and wins over a translated header. `visible` is accepted but read by nothing. `baseDatatypeCd` is read only where the dataset projects no columns of its own.

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

@@ -79,6 +79,7 @@ For each 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)
+- [ ] A `grid`/`list` view's `groupByField` and every `groupByOptions` entry is a dropdown, flags, reference or user column; `groupByOptions` includes `groupByField`; `collapsedGroups` has a valid `groupByField` and, for a dropdown, lists only its option values. **Rejected at validate/install**
 - [ ] 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)
 
 ## Menus