@dforge-core/dforge-mcp 0.1.0-rc.9 → 0.1.2

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

@@ -0,0 +1,245 @@
+# Data Views Reference
+
+Data views define how users see and interact with entity data. One entity can have many data views (grid, kanban, gallery, tree-grid, list, calendar, matrix, card).
+
+Lives in: `ui/data_views.json`
+
+## Structure
+
+```json
+{
+    "contact_list": {
+        "label": "All Contacts",
+        "description": "Primary list of contacts",
+        "viewType": "grid",
+        "icon": "bi-people",
+        "dataSources": [{
+            "entityCode": "contact",
+            "label": "Contacts",
+            "columns": [
+                { "column_cd": "first_name", "width": 150 },
+                { "column_cd": "last_name",  "width": 150 },
+                { "column_cd": "email",      "width": 220 },
+                { "column_cd": "phone",      "width": 130 },
+                { "column_cd": "account",    "width": 200 }
+            ],
+            "filter": null
+        }],
+        "order": ["last_name"]
+    }
+}
+```
+
+## Critical rule — `dataSources` array
+
+**Always** put `entityCode`, `columns`, and per-source `filter` inside a `dataSources` array. Never at the root. The view-level `order` and `filter` sit at the view-def root, alongside `viewType`.
+
+```json
+// WRONG — will fail validation
+{
+    "contact_list": {
+        "label": "Contacts",
+        "viewType": "grid",
+        "entityCode": "contact",        // WRONG — should be inside dataSources
+        "columns": [ /* ... */ ]        // WRONG — should be inside dataSources
+    }
+}
+
+// RIGHT
+{
+    "contact_list": {
+        "label": "Contacts",
+        "viewType": "grid",
+        "dataSources": [{
+            "entityCode": "contact",
+            "columns": [ /* ... */ ]
+        }]
+    }
+}
+```
+
+## View types
+
+| `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 |
+| `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) |
+| `calendar` | Calendar display of date-based records | `dateField`, `titleField` | Schedules, due dates, events |
+| `matrix` | Pivot grid: `rowAxis` × `colAxis`, one value-source record per cell | `rowAxis`, `colAxis`, `cell` | Cross-tab data: P&L (accounts × periods), timesheets (tasks × days), budgets (categories × months) |
+| `card` | Single-record detail view | — | Record detail pages (implicit — every entity has one) |
+
+## View config (`viewConfig`)
+
+Some view types need additional configuration via the `viewConfig` property:
+
+### Kanban
+
+```json
+{
+    "opportunities_kanban": {
+        "viewType": "kanban",
+        "label": "Sales Pipeline",
+        "dataSources": [{
+            "entityCode": "opportunity",
+            "columns": ["opportunity_name", "account", "total_amount", "owner_id"]
+        }],
+        "viewConfig": {
+            "groupByField": "stage"
+        }
+    }
+}
+```
+
+`groupByField` — the dropdown/status column to group cards by. Each distinct value becomes a kanban column.
+
+### Calendar
+
+```json
+{
+    "invoices_calendar": {
+        "viewType": "calendar",
+        "label": "Invoice Calendar",
+        "dataSources": [{
+            "entityCode": "invoice",
+            "columns": ["invoice_number", "customer", "total_amount", "due_date"]
+        }],
+        "viewConfig": {
+            "dateField": "due_date",
+            "titleField": "invoice_number"
+        }
+    }
+}
+```
+
+- `dateField` — the date column that determines where records appear on the calendar
+- `titleField` — the column whose value is shown as the calendar event title
+
+### Matrix
+
+A pivot grid. The view's primary `dataSources` entity is the **cell** entity (one record per row×column intersection). `viewConfig` declares the two axes and how the cell record maps onto them.
+
+```json
+{
+    "income_statement_matrix": {
+        "viewType": "matrix",
+        "label": "Income Statement (Matrix)",
+        "dataSources": [{
+            "entityCode": "balance_register",
+            "columns": ["account_id", "period_key", "pl_amount"]
+        }],
+        "viewConfig": {
+            "rowAxis": {
+                "kind": "dataset",
+                "entity": "account",
+                "labelField": "account_name",
+                "filter": { "c": "statement", "o": "eq", "v": "IncomeStatement" },
+                "sort": [{ "col": "account_code", "dir": "asc" }]
+            },
+            "colAxis": {
+                "kind": "dataset",
+                "entity": "accounting_period",
+                "labelField": "description",
+                "lockedField": "closed",
+                "hideEmpty": true,
+                "sort": [{ "col": "period_key", "dir": "asc" }]
+            },
+            "cell": {
+                "entity": "balance_register",
+                "rowKey": "account_id",
+                "colKey": "period_key",
+                "fields": ["pl_amount"],
+                "editable": false,
+                "drill": true
+            }
+        }
+    }
+}
+```
+
+**`rowAxis` / `colAxis`** — what the rows and columns are. Three `kind`s:
+
+- `"dataset"` — axis values are an entity's records. `entity` + `labelField` required; optional `keyField` (defaults to the axis entity PK — what the cell's `rowKey`/`colKey` matches), `lockedField` (boolean column → that axis value's cells are read-only), `filter` (same `{c,o,v}` grammar as everywhere — scopes which axis records load), `hideEmpty` (**column axis only** — drop columns with no cell record in any row, e.g. periods with no postings; ignored if it would blank the whole grid), `rangeControl` (**column axis only** — show a From/To range control so the user can narrow the visible columns to a span; persists in view options; composes with `hideEmpty`), `sort` (`[{ col, dir }]`).
+- `"dropdown"` — axis values are a dropdown/flags column's options. `kind` + `column` (an `"entity.column"` reference); optional `values` (`[...]` of option value codes — a subset + order of columns, chosen the way kanban lanes are; omit to show every option in field order). Codes line up by construction.
+- `"date"` — generated date window, **column axis only** (not valid on `rowAxis`). `kind` + `grain: "day"` + `window: "week"` (v1). *Roadmap (designed, not built): arbitrary `range` (`{from, to}`) + `grain` (`day`/`week`/`month`/`quarter`/`year`), surfaced as a date-picker variant of the range bar — lets a time matrix generate its columns instead of needing seeded period records. Don't author against it yet.*
+
+> **The matrix is source-agnostic.** A matrix is just config over generic entities: point the cell at *any* dated/keyed entity that fits your model — a pre-aggregated registry (e.g. `gl.balance_register`, fast but period-grained), raw dated movements (any-grain, heavier), or your own table. `gl` is a regular, replaceable module, not a platform requirement; nothing about the matrix knows or needs "gl". Choosing a pre-aggregated source vs raw rows (and the grain) is a per-view config decision, with the usual perf-vs-flexibility trade.
+
+**`cell`** — the value-source record at each intersection. `entity` (must match the primary dataSource), `rowKey` / `colKey` (cell columns matching the row/column axis keys), `fields` (cell columns rendered in each cell). Optional: `cardinality: "one"` (v1 default), `editable`, `drill` (read-only cells become clickable → open the cell record and its child sets), `seedFromRow` (`{ cellField: rowAxisField }` copied into new cell records on insert), `seedCurrentUser` (cell fields set to the current user id on insert).
+
+## Columns
+
+Each column is either a simple string or an object:
+
+```json
+"columns": [
+    "first_name",                                // just column code, default width
+    { "column_cd": "email", "width": 220 },      // with width override
+    { "column_cd": "account", "width": 200, "visible": true }
+]
+```
+
+## Filters
+
+Filters use dForge's canonical JSON filter format — see [filters.md](filters.md) for the full grammar. Keys are `c` (column), `o` (operator), `v` (value) for conditions, and `g` (group operator), `i` (items) for groups.
+
+Single condition:
+
+```json
+"filter": { "c": "status", "o": "=", "v": "active" }
+```
+
+Group:
+
+```json
+"filter": {
+    "g": "and",
+    "i": [
+        { "c": "status", "o": "=", "v": "active" },
+        { "c": "created_date", "o": ">", "v": "2026-01-01" }
+    ]
+}
+```
+
+Do **not** use `op`/`args`/`column`/`value` — that format is rejected.
+
+## Sort (`order`)
+
+Sort lives at the **view-def root** (not inside `dataSources[]`) under the key **`order`** — a `string[]` of column codes. Direction is encoded in the string itself:
+
+- Bare column code → **ascending** (the default; no prefix needed)
+- Leading `-` → **descending**
+
+```json
+"order": ["last_name", "first_name"]          // both ascending
+"order": ["-created_date"]                     // descending (audit trait provides created_date)
+"order": ["-created_date", "last_name"]        // primary desc, then asc tiebreak
+```
+
+The array order is the sort precedence: the first entry is the primary sort key, subsequent entries are tiebreakers.
+
+This matches the shape the runtime persists and `data.get` accepts. **Do not** use `"sort"`, `[{ column_cd, direction }]`, or `[{ c, d }]` here — those shapes belong to `query.run` and `report.run` (see [queries.md](queries.md)), not `data_views.json`.
+
+## Multi-source views
+
+A view can show data from multiple entities (e.g. a dashboard-style view mixing contacts and activities). Each entry in `dataSources` is independent with its own columns/filter.
+
+```json
+"dataSources": [
+    { "entityCode": "contact", "columns": [ /* ... */ ] },
+    { "entityCode": "activity", "columns": [ /* ... */ ] }
+]
+```
+
+Most views only have one source. Order is view-level and applies to the primary (level 0) source.
+
+## Common mistakes
+
+- Putting `entityCode` or `columns` at the root — **wrong**. They go inside `dataSources[]`.
+- Using `viewCode` or `view_cd` — **wrong**. The code is the dictionary key.
+- Using `"sort"` for data view ordering — **wrong**. The field is `"order"` and it lives at view-def root (not inside `dataSources[]`).
+- Object-array order like `[{ column_cd: "...", direction: "asc" }]` — **wrong shape for data views**. Use `string[]` with leading `-` for descending.
+- `viewType` is **optional** — omitted or unknown values fall back to `grid` at runtime. Set it explicitly for any non-grid view (`kanban`, `calendar`, `matrix`, …); a `matrix` view also **requires** a `viewConfig` with `rowAxis`/`colAxis`/`cell`.
+- Inventing view types like `"spreadsheet"` or `"table"` — **wrong**. Use `grid`.

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

@@ -0,0 +1,61 @@
+# Importing a data model from a spreadsheet (.xlsx / .csv)
+
+When the user gives you a spreadsheet to turn into a module, you can't read a
+binary `.xlsx` directly — decode it first, then reason over the result.
+
+## Flow
+
+1. **Extract the sheets to a JSON model.** Load the bundled extractor resource
+   `dforge://script/xlsx-to-model`, write it to a temp file, and run it:
+
+   ```bash
+   python3 /tmp/xlsx_to_model.py "<path/to/file.xlsx>"
+   ```
+
+   It needs only Python 3 (pure standard library — no `pip install`). It prints
+   `{"sheets":[{"name":..,"headers":[..],"rows":[[..],..]}]}`. If it prints
+   `{"error":..}` (e.g. Python missing), fall back: ask the user to export each
+   sheet as **CSV** (CSV is plain text — read it directly).
+
+2. **Turn the model into a table-spec.** For each sheet:
+   - `name` = the sheet name, snake_cased (`"Order Lines"` → `order_lines`).
+   - One **column** per header: `name` = header snake_cased; `sampleValues` =
+     that column's values from `rows` (a few are enough). Don't set `fieldTypeCd`
+     unless you're sure — let the import infer it. Add a `sqlType` hint only when
+     the values make the type obvious (all integers → `int`, decimals → `numeric`,
+     `YYYY-MM-DD` strings → `date`; remember xlsx **dates arrive as numbers**, so
+     lean on the header name, e.g. `*_date`, to spot them).
+   - **References (FKs):** when a column looks like a foreign key — header
+     `<thing>_id` (or `<thing> id`) where `<thing>` matches another sheet — put it
+     in `references: [{ column, toTable }]` instead of as a plain column.
+   - Skip an `id` / primary-key column — the `identity` trait provides `{entity}_id`.
+
+3. **Show the proposed entity inventory for sign-off** (same gate as any Phase 1
+   scaffold), then call **`dforge_module_import`**:
+   - existing module → `{ moduleDir, tables }`
+   - new module → add `module: { code, displayName }` (greenfield).
+
+4. **Run `dforge_module_validate`** and refine the generated default grids to
+   surface the imported columns.
+
+## With data or empty — both work
+
+A sheet may be **populated** (headers + rows) or **structure-only** (headers, no
+data rows). Both produce a valid entity:
+
+- **Populated** → use the `sampleValues` for type inference (numbers, dates,
+  dropdowns). Best results.
+- **Empty (headers only)** → the extractor returns `"rows": []`. You still get
+  one column per header, but with no samples the import defaults most columns to
+  `text` — so lean on the **header name** (`email`, `phone`, `*_date`, `*_id` →
+  FK) and add `sqlType` hints where the user can tell you the type. Consider
+  confirming the inferred types with the user before importing.
+
+## Notes
+
+- One worksheet (or one Excel table object) = one entity. Ignore obviously
+  non-tabular sheets (dashboards, notes).
+- The extractor returns the first non-empty row as `headers`; if a sheet has
+  title rows above the real header, tell the user or adjust the spec by hand.
+- Type inference + the FK+Reference pattern are handled by `dforge_module_import`
+  against the `@dforge-core/metadata` registry — you only produce the table-spec.

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

@@ -0,0 +1,144 @@
+# Field Types Reference
+
+The canonical list of field types supported by dForge. **Do not invent new values — the set is fixed** and validated by the platform on module install.
+
+Source of truth: `server/database/system-modules/metadata/seed-data/field_types.json` in the dForge repo.
+
+> **You usually don't set `dbDatatype`.** For a plain data column, omit it — the field tools derive it from `fieldTypeCd` (the "Common `dbDatatype`" column below): `currency` → `numeric(18,2)`, `text` → `varchar`, `checkbox` → `bool`, etc. An explicit value is never overridden, so only set `dbDatatype` when you need to:
+> - **a hidden FK column** — it has no `fieldTypeCd`, so derivation can't fire; set `dbDatatype: "cuid"` to match the target entity's `identity` PK (see `column-types.md`);
+> - **override the size/precision** — e.g. `varchar(100)` via `maxLen`, or a specific numeric scale.
+>
+> Reference (`columnType: "R"`) and formula (`columnType: "F"`) columns never get a `dbDatatype` at all.
+
+## String-backed
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `text` | `string` | Single-line text | `varchar` (with `maxLen`) | `maxLen` |
+| `email` | `string` | Email address. Client-side format validation. | `varchar` 250 | — |
+| `phone` | `string` | Phone/telephone. | `varchar` 50 | — |
+| `url` | `string` | Web URL. | `varchar` 500 | — |
+| `textarea` | `string` | Multi-line plain text. | `text` | `defaultLines`, `maxLines` |
+| `richtext` | `string` | Rich text editor (HTML). | `text` | — |
+| `code` | `string` | Code editor with syntax highlighting. | `text` | `language` |
+| `dropdown` | `string` | Fixed list of options. | `varchar` | `options: ["a","b",…]` or `[{value,label,icon,color}]` |
+| `flags` | `string` | Multiple checkboxes with letter flags. | `varchar` | `optionSets`, `style: "buttons"` |
+| `tags` | `string` | Free-form tag list. | `varchar` or `text` | — |
+| `color` | `string` | Color picker. | `varchar(20)` | — |
+| `hidden` | `string` | Internal, never shown in UI. | `varchar` | — |
+
+## Number-backed
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `number` | `number` | Numeric value. | `int`, `bigint`, `numeric` | `min`, `max`, `scale` |
+| `currency` | `number` | Monetary value. Precision 2. | `numeric(18,2)` | `currency: "USD"`, `min`, `max` |
+| `percent` | `number` | Percentage 0–100. Precision 2. | `numeric(5,2)` | `min`, `max` (default 0–100) |
+
+## Boolean-backed
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `checkbox` | `bool` | Boolean checkbox. | `bool` | — |
+
+> **`checkbox` is the only valid `fieldTypeCd` for boolean fields.** Do not use `bool`, `boolean`, or `toggle` as `fieldTypeCd` — those are not valid field type codes. (`bool` IS the correct `dbDatatype` for this field, but `checkbox` is the only correct `fieldTypeCd`.)
+
+## Date/time-backed
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
+|---|---|---|---|---|
+| `date` | `date` | Calendar date only. | `date` | `min`, `max` (ISO strings or `TODAY()`) |
+| `datetime` | `timestamp` | Date + time with timezone. | `timestamptz` | `min`, `max` |
+| `time` | `time` | Time of day. | `time` | — |
+
+## Binary / file
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description | Params |
+|---|---|---|---|
+| `file` | `binary` | Arbitrary file upload. | `accept`, `maxSize` |
+| `image` | `binary` | Image upload with preview. | `maxSize`, `dimensions` |
+
+## Reference / lookup / set
+
+| `fieldTypeCd` | `baseDatatypeCd` | `columnType` | Description |
+|---|---|---|---|
+| `lookup` | `guid` | `R` | Reference to another entity (always paired with a hidden FK column — see SKILL.md "FK+Reference pattern") |
+| `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. |
+| `entitylink` | `json` | `D` | Polymorphic link to any entity (stores `{entity, id}` pair). |
+
+## JSON
+
+| `fieldTypeCd` | `baseDatatypeCd` | Description |
+|---|---|---|
+| `json` | `json` | JSON editor. Stored in `jsonb`. |
+
+---
+
+## Default values
+
+There is **no** `defaultValue` (or `default`) key on an entity data column — it fails schema
+validation (`entity.schema.json` is `additionalProperties: false`). To give a column a default:
+
+| Need | Do this |
+|---|---|
+| Literal / computed default (`'draft'`, `TODAY()`) | Carry a `formula` on the column (formula context — uppercase `TODAY()`/`NOW()`), e.g. `"formula": "'draft'"` or `"formula": "TODAY()"`. |
+| Document number (PO-2026-0001) | Declare a `numberSequence` on the entity — auto-fills on insert. |
+| Anything set at create time | Set it in an action/trigger DSL (`execute:` uses lowercase `now()`). |
+
+> `defaultValue` **is** valid on **module settings** (`settings.json`) — that's the only place it
+> belongs. Don't carry the settings habit over to entity fields.
+
+---
+
+## Common mistakes
+
+> **Wrong key name:** `fieldType` is a C# navigation property on the server model — it is not a valid JSON key in entity definitions. Always use `fieldTypeCd` (the string code). Using `fieldType: { ... }` or `fieldType: "date"` causes the platform to silently ignore the field type, producing null constraint errors on save.
+
+> **No `defaultValue` on entity fields:** `defaultValue` is a *settings* key, not a column key — on a field it fails schema validation. Set a column default with a `formula`, a `numberSequence`, or DSL logic (see "Default values" above).
+
+### Wrong `dbDatatype` values
+
+These are SQL type names LLMs tend to use for `dbDatatype`. **They are all wrong.** The right values come from the tables above.
+
+| Wrong `dbDatatype` | Right `dbDatatype` | Used with `fieldTypeCd` |
+|---|---|---|
+| `datetime` | `timestamptz` | `datetime` |
+| `timestamp` | `timestamptz` | `datetime` |
+| `boolean` | `bool` | `checkbox` |
+| `string` | `varchar` (with `maxLen`) or `text` | `text`, `textarea`, `dropdown`, … |
+| `integer` | `int` or `bigint` | `number` |
+| `float`, `double`, `decimal` | `numeric` | `number`, `currency`, `percent` |
+| `number` | `int`, `bigint`, or `numeric` | `number`, `currency`, `percent` |
+
+### Wrong `fieldTypeCd` values
+
+These are the field type names LLMs tend to invent. **They are all wrong.**
+
+| Wrong | Right |
+|---|---|
+| key `fieldType: { fieldTypeCd: "date", ... }` | key `fieldTypeCd: "date"` (plain string) |
+| key `fieldType: "date"` | key `fieldTypeCd: "date"` |
+| `bool`, `boolean` | `checkbox` |
+| `integer` | `number` |
+| `float` | `number` |
+| `decimal` | `number` with `scale` param |
+| `datePicker` | `date` |
+| `timestamp` | `datetime` |
+| `money` | `currency` |
+| `select`, `enum` | `dropdown` |
+| `multiselect` | `flags` or `tags` |
+| `autocomplete` | `lookup` |
+| `reference` | `lookup` |
+| `relation` | `lookup` or `grid` |
+| `link` | `url` |
+| `picture`, `photo` | `image` |
+| `attachment` | `file` |
+| `multiline` | `textarea` |
+| `richText`, `markdown` | `richtext` |
+| `userPicker` | `user` |
+| `phoneNumber` | `phone` |
+
+## When in doubt
+
+If the user describes a field type that isn't in this list (e.g. "rating stars", "geo location", "signature pad"), those field types **do not currently exist**. Do not fabricate a `fieldTypeCd` value. Tell the user what's available and ask how they'd like to model it with existing types (e.g. rating as `number` with `min: 1, max: 5`, geo location as two `number` columns or a `json` column).