@dforge-core/dforge-mcp 0.1.0-rc.12 → 0.1.0-rc.13

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

@@ -0,0 +1,326 @@
+# Filter Format Reference
+
+dForge uses **one canonical JSON filter format everywhere** — folder row filters, data view filters, API filters, report dataset filters, and user ad-hoc filters. Learn it once, use it everywhere.
+
+This is the single filter format used across the entire dForge platform.
+
+## Basic structure
+
+A filter is either a **single condition** or a **group** of conditions.
+
+### Condition — single comparison
+
+```json
+{ "c": "status", "o": "=", "v": "draft" }
+```
+
+| Key | Type | Description |
+|---|---|---|
+| `c` | string | Column code (field name on the entity) |
+| `o` | string | Operator (see table below) |
+| `v` | any | Value to compare against |
+
+### Group — logical combination
+
+```json
+{
+    "g": "and",
+    "i": [
+        { "c": "status", "o": "=", "v": "draft" },
+        { "c": "amount", "o": ">", "v": 1000 }
+    ]
+}
+```
+
+| Key | Type | Description |
+|---|---|---|
+| `g` | string | Group operator: `and`, `or`, `!and` (NAND), `!or` (NOR) |
+| `i` | array | Items — conditions and/or nested groups |
+
+Groups can nest to arbitrary depth.
+
+## Operators
+
+### Condition operators
+
+| Operator | Description | Example value |
+|---|---|---|
+| `=` or `eq` | Equal | `"draft"` |
+| `!=` or `notEq` | Not equal | `"cancelled"` |
+| `>` or `gr` | Greater than | `1000` |
+| `>=` or `grEq` | Greater than or equal | `1000` |
+| `<` or `less` | Less than | `100` |
+| `<=` or `lessEq` | Less than or equal | `100` |
+| `between` or `btw` | Between (inclusive) | `[100, 500]` |
+| `!between` or `nBetween` | Not between | `[100, 500]` |
+| `contains` | Contains substring | `"acme"` |
+| `!contains` or `nContain` | Does not contain | `"test"` |
+| `start` | Starts with | `"INV-"` |
+| `!start` or `nStart` | Does not start with | `"DRAFT-"` |
+| `end` | Ends with | `".pdf"` |
+| `!end` or `nEnd` | Does not end with | `".tmp"` |
+| `mask` | Pattern match (SQL LIKE) | `"INV-2025-%"` |
+| `!mask` or `nMask` | Does not match pattern | `"TEST-%"` |
+| `null` or `empty` | Is null/empty | _(no `v` needed)_ |
+| `!null` or `nEmpty` | Is not null | _(no `v` needed)_ |
+| `in` | In a set | `["draft", "pending"]` |
+| `!in` or `nIn` | Not in a set | `["cancelled", "deleted"]` |
+| `eqRef` | Equal to another column | `"other_column_cd"` |
+| `f` | Function (dynamic runtime value) | `{ "fn": "isToday" }` |
+
+### Function operator — dynamic runtime values
+
+The function operator `f` evaluates a named function at query time instead of comparing against a static value. The value must be an object: `{ "fn": "<functionId>" }`.
+
+| Function | Column types | Description |
+|---|---|---|
+| `isToday` | date, timestamp | `column = CURRENT_DATE` |
+| `isYesterday` | date, timestamp | `column = CURRENT_DATE - 1` |
+| `isThisWeek` | date, timestamp | Within current ISO week |
+| `isThisMonth` | date, timestamp | Within current month |
+| `isThisYear` | date, timestamp | Within current year |
+| `isPast` | date, timestamp | `column < NOW()` |
+| `isFuture` | date, timestamp | `column > NOW()` |
+| `isCurrentUser` | guid | `column = <logged-in user ID>` |
+
+```json
+{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }
+```
+
+```json
+{ "c": "owner_id", "o": "f", "v": { "fn": "isCurrentUser" } }
+```
+
+Function conditions require **no value input** — the function provides the comparison logic at runtime.
+
+**Functions are valid only with the `f` operator.** They cannot be used as the value of `<`, `>`, `=`, `!=`, `between`, or any other comparison operator — each function already encodes its own comparison (e.g. `isPast` means "column < NOW()"). If you need to combine a dynamic-date check with another condition, put them as separate items in an `and`/`or` group:
+
+```json
+{
+    "g": "and",
+    "i": [
+        { "c": "due_date", "o": "f", "v": { "fn": "isPast" } },
+        { "c": "status", "o": "!=", "v": "done" }
+    ]
+}
+```
+
+These are **wrong** and will be rejected:
+
+```json
+{ "c": "due_date", "o": "<", "v": "@TODAY" }
+{ "c": "due_date", "o": "<", "v": { "fn": "isToday" } }
+```
+
+### Group operators
+
+| Operator | SQL equivalent |
+|---|---|
+| `and` | `A AND B AND C` |
+| `or` | `A OR B OR C` |
+| `!and` | `NOT (A AND B AND C)` — at least one is false |
+| `!or` | `NOT (A OR B OR C)` — none are true |
+
+## Where filters are used
+
+### 1. Folder row filters (`ui/folders.json`)
+
+Scope which records are visible in a subfolder. Used in `rowFilter` property on entity membership:
+
+```json
+"stock": {
+    "viewName": "default",
+    "quickAdd": true,
+    "rowFilter": { "c": "warehouse_id", "o": "eq", "v": 2001 }
+}
+```
+
+Generates: only stock records where `warehouse_id = 2001` appear in this folder.
+
+For compound filters on a folder:
+
+```json
+"rowFilter": {
+    "g": "and",
+    "i": [
+        { "c": "warehouse_id", "o": "eq", "v": 2001 },
+        { "c": "status", "o": "!=", "v": "archived" }
+    ]
+}
+```
+
+### 2. Data view filters (`ui/data_views.json`)
+
+Pre-filter which records appear in a data view:
+
+```json
+{
+    "active_leads": {
+        "viewType": "grid",
+        "label": "Active Leads",
+        "dataSources": [{
+            "entityCode": "lead",
+            "columns": ["name", "email", "stage", "owner_id"],
+            "filter": {
+                "g": "and",
+                "i": [
+                    { "c": "stage", "o": "!=", "v": "Closed Lost" },
+                    { "c": "stage", "o": "!=", "v": "Converted" }
+                ]
+            },
+            "sort": [{ "column_cd": "created_date", "direction": "desc" }]
+        }]
+    }
+}
+```
+
+### 3. Report dataset filters
+
+Same format inside report dataset definitions:
+
+```json
+"datasets": {
+    "ds_pipeline": {
+        "entityCode": "opportunity",
+        "columns": ["stage", "total_amount"],
+        "filter": {
+            "g": "and",
+            "i": [
+                { "c": "stage", "o": "!in", "v": ["Closed Won", "Closed Lost"] },
+                { "c": "total_amount", "o": ">", "v": 0 }
+            ]
+        },
+        "groupBy": ["stage"],
+        "aggregations": {
+            "total_value": { "func": "sum", "column": "total_amount" }
+        }
+    }
+}
+```
+
+### 4. API filters (`data.get` calls)
+
+Same format passed as the `filter` parameter in RPC calls:
+
+```json
+{
+    "method": "data.get",
+    "params": {
+        "entityCode": "contact",
+        "filter": { "c": "account_id", "o": "=", "v": "some-uuid" },
+        "columns": ["first_name", "last_name", "email"]
+    }
+}
+```
+
+### 5. Action DSL (`query()` is different!)
+
+**Important**: the `query()` function in action DSL uses **raw parameterized SQL**, NOT the JSON filter format:
+
+```javascript
+// This is SQL, not a JSON filter
+var results = query('SELECT * FROM crm.contact WHERE account_id = @accId AND status = @status', {
+    accId: [account_id],
+    status: 'active'
+})
+```
+
+The JSON filter format is only used in **declarative contexts** (folders, views, reports, API calls). Action DSL uses SQL directly.
+
+## Common examples
+
+### Filter by status (single condition)
+
+```json
+{ "c": "status", "o": "=", "v": "active" }
+```
+
+### Exclude multiple statuses
+
+```json
+{ "c": "status", "o": "!in", "v": ["cancelled", "deleted", "archived"] }
+```
+
+### Date range
+
+```json
+{
+    "g": "and",
+    "i": [
+        { "c": "created_date", "o": ">=", "v": "2026-01-01" },
+        { "c": "created_date", "o": "<", "v": "2026-04-01" }
+    ]
+}
+```
+
+Or using `between`:
+
+```json
+{ "c": "amount", "o": "between", "v": [1000, 5000] }
+```
+
+### Non-null check
+
+```json
+{ "c": "email", "o": "!null" }
+```
+
+### String matching
+
+```json
+{ "c": "invoice_number", "o": "start", "v": "INV-2026-" }
+```
+
+### Complex: active records in sales or marketing
+
+```json
+{
+    "g": "and",
+    "i": [
+        { "c": "is_active", "o": "=", "v": true },
+        {
+            "g": "or",
+            "i": [
+                { "c": "department", "o": "=", "v": "sales" },
+                { "c": "department", "o": "=", "v": "marketing" }
+            ]
+        }
+    ]
+}
+```
+
+### Column-to-column comparison
+
+```json
+{ "c": "ship_date", "o": "eqRef", "v": "order_date" }
+```
+
+Generates: `WHERE ship_date = order_date`
+
+## Filter composition at query time
+
+All filter layers are **ANDed together** automatically:
+
+```
+Effective filter = folder_row_filter AND view_filter AND api_filter AND user_ad_hoc_filter
+```
+
+The user never sees a record unless it passes **all** layers. You don't need to duplicate folder filters in view filters — they compose automatically.
+
+## Rules
+
+- **`null` filter** (or omitted) means no filtering — show everything the user has access to.
+- **Single condition** is valid without a group wrapper.
+- Use **short operators** (`=`, `!=`, `>`) or **enum keys** (`eq`, `notEq`, `gr`) — both work.
+- For folder `rowFilter` in module packages, prefer the short compact form: `{ "c": "...", "o": "eq", "v": ... }`.
+- Dates are ISO strings: `"2026-01-01"`.
+- Arrays for `in`/`between`: `["a", "b"]` or `[100, 500]`.
+
+## Common mistakes
+
+- Using the JSON filter format inside `query()` in DSL actions — **wrong**. `query()` uses raw SQL.
+- Wrapping a single condition in a group unnecessarily — **valid but noisy**. A bare condition is fine.
+- Using `"operator": "equals"` — **wrong**. Use `"o": "="` or `"o": "eq"`.
+- Using `"column": "status"` — **wrong**. Use `"c": "status"`.
+- Forgetting that `null` means "no filter" (not "filter by null") — to filter for null values, use `{ "c": "field", "o": "null" }`.
+- Putting a `{ "fn": "..." }` object (or `@TODAY`/`@CURRENT_USER` placeholder) as the value of a normal comparison like `<`, `>`, `=` — **wrong**. Functions are standalone conditions that only work with `"o": "f"`.

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

@@ -0,0 +1,73 @@
+# Column Flags Reference
+
+Column flags are single-letter codes concatenated into a string. Order doesn't matter — `"VEM"` and `"EMV"` are equivalent.
+
+Valid flags regex: `^[VIEMH]*$`
+
+## Flag letters
+
+| Letter | Name | Meaning |
+|---|---|---|
+| `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). |
+| `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.
+
+## 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 |
+| `"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 |
+| `"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.
+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.
+6. **Don't mix `I` with `V` or `E`** — internal columns are not user-facing.
+
+## Entity rights flags (different namespace — roles only)
+
+These letters appear in role `rights` declarations, **NOT** on column flags. Don't confuse them:
+
+| Letter | Permission | Used on |
+|---|---|---|
+| `S` | Select (read rows) | Entity in role `rights` |
+| `I` | Insert (create rows) | Entity in role `rights` |
+| `U` | Update (modify rows) | Entity in role `rights` |
+| `D` | Delete (remove rows) | Entity in role `rights` |
+| `C` | Clone (duplicate row) | Entity in role `rights` |
+| `E` | Execute | Actions, reports, folders in role `rights` |
+
+So `"SIUD"` on a role grants full CRUD; `"SI"` grants read + create only.
+
+**Note**: the `I` in column flags (Internal) and the `I` in role rights (Insert) are different concepts using the same letter. Context makes them unambiguous — column flags go on entity fields, role rights go on `security/roles.json`.
+
+## How uniqueness, PKs, and search work
+
+These are **NOT** flag letters. They're separate properties on the column definition:
+
+| Need | How to declare | NOT this |
+|---|---|---|
+| Primary key | `"isPk": true` (or use `identity` trait) | NOT a `P` flag |
+| Unique column | Add a unique index in the entity's `indexes` block, or `"isUnique": true` | NOT a `U` flag |
+| Searchable | Configure in data view columns or search settings | NOT an `S` flag |
+
+## Mistakes to avoid
+
+- 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.
+- 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

@@ -0,0 +1,206 @@
+# Formula Engine Reference
+
+Formulas are used in:
+
+- **Formula columns** (`columnType: "F"`) — computed values
+- **Action `canExecute:` blocks** — availability checks
+- **Default values** — a setting's `formula` (e.g. `"formula": "TODAY()"`) or a formula (`F`) column. Note: entity *data* columns have **no** `default`/`defaultValue` key — model a default with an `F` column or set it in action/trigger logic.
+- **Filter expressions** (partially)
+- **Validation expressions** (partially)
+
+> These are **formula** contexts: date helpers are uppercase `TODAY()` / `NOW()` here. Action
+> `execute:` blocks are **not** a formula context — they run as JavaScript and use lowercase
+> `now()` (see `action-dsl.md`).
+
+The same grammar applies everywhere.
+
+## Basic syntax
+
+- **Field references**: `[column_name]` — the value of another column on the same entity
+- **Navigation**: `[reference_column].[field]` — traverse a reference to a related entity's field
+- **Literals**: numbers (`42`, `3.14`), strings (`'hello'` or `"hello"`), booleans (`true`, `false`), null (`null`)
+- **Operators**: `+`, `-`, `*`, `/`, `%`, `==`, `!=`, `<`, `>`, `<=`, `>=`, `AND`, `OR`, `NOT`
+- **Function calls**: `FUNCTION_NAME(arg1, arg2, ...)` — uppercase by convention
+- **Parentheses** for grouping
+
+## Examples
+
+```
+[first_name] + ' ' + [last_name]
+
+[quantity] * [unit_price]
+
+[account].[name]
+
+[account].[billing_address].[country]
+
+[status] == "active" AND [balance] > 0
+
+CASE([priority], "high", 3, "medium", 2, "low", 1, 0)
+
+IF([total] > 1000, "large", "small")
+
+COALESCE([nickname], [first_name], "Unknown")
+
+FORMAT([created_date], "yyyy-MM-dd")
+```
+
+## Built-in functions
+
+### String functions
+
+- `CONCAT(a, b, ...)` — concatenate strings
+- `LEN(s)` — string length
+- `UPPER(s)`, `LOWER(s)` — case conversion
+- `TRIM(s)`, `LTRIM(s)`, `RTRIM(s)` — whitespace removal
+- `SUBSTRING(s, start, len)` — substring
+- `REPLACE(s, find, with)` — replace substring
+- `CONTAINS(s, find)` — boolean substring check
+- `STARTSWITH(s, prefix)`, `ENDSWITH(s, suffix)` — boolean
+- `FORMAT(value, pattern)` — format dates/numbers
+
+### Number functions
+
+- `ABS(n)`, `ROUND(n, digits)`, `FLOOR(n)`, `CEIL(n)`, `CEILING(n)`
+- `MIN(a, b)`, `MAX(a, b)` — binary min/max
+- `POW(base, exp)`, `SQRT(n)`
+- `MOD(a, b)` — modulo
+
+### Date functions
+
+- `TODAY()` — current date
+- `NOW()` — current datetime with timezone
+- `YEAR(d)`, `MONTH(d)`, `DAY(d)` — date parts
+- `HOUR(dt)`, `MINUTE(dt)`, `SECOND(dt)` — time parts
+- `DATEADD(d, count, unit)` — add time (unit: `day`, `month`, `year`, `hour`, `minute`)
+- `DATEDIFF(a, b, unit)` — difference between dates
+
+### Logical functions
+
+- `IF(cond, then, else)` — ternary
+- `CASE(expr, val1, result1, val2, result2, ..., default)` — multi-branch
+- `COALESCE(a, b, c, ...)` — first non-null
+- `NULLIF(a, b)` — null if equal, else a
+- `ISNULL(x)` — boolean null check
+
+### Aggregation (on set columns)
+
+- `COUNT([set_column])` — count related rows
+- `SUM([set_column].[field])` — sum a child field over a set
+- `AVG`, `MIN`, `MAX` similarly
+
+Put set aggregations in a **Formula (`F`) column** — they evaluate at query time and may reference
+any child column, including the child's own formula columns, e.g. `SUM([lines].[line_total])`.
+
+> ⛔ Do **not** put a `SUM([set].[field])` in a **Generated (`G`)** column unless `field` is a
+> *physical* (`D`) column. A `G` aggregate is maintained by a DB trigger that reads the child's
+> `OLD`/`NEW` physical values; aggregating a virtual `F` child fails at install with
+> `db_error: column old.<field> does not exist`. See `column-types.md` → "Roll-up totals over child rows".
+
+## Navigation (dot notation)
+
+`[reference].[field]` traverses a reference column to a target entity:
+
+```
+[account].[name]                         -- contact's account's name
+[owner].[email]                          -- owner user's email
+[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.
+
+## 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.
+
+You don't declare which is which — the engine detects it from the formula's AST.
+
+## Setting references
+
+In modules that use settings, formulas can reference setting values with `$[SettingName]` syntax:
+
+```
+[total] * $[VAT_Rate]
+```
+
+## Validation and CHECK constraints
+
+Check constraints use a subset of the formula grammar. The server parses them to AST and converts to SQL. Common patterns:
+
+```
+[quantity] > 0
+[end_date] >= [start_date]
+[email] LIKE '%@%'
+```
+
+## Examples — full formula columns
+
+### Full name
+
+```json
+"full_name": {
+    "columnType": "F",
+    "fieldTypeCd": "text",
+    "baseDatatypeCd": "string",
+    "flags": "V",
+    "orderNum": 25,
+    "formula": "[first_name] + ' ' + [last_name]",
+    "description": "Full Name"
+}
+```
+
+### Line total (quantity × price)
+
+```json
+"line_total": {
+    "columnType": "F",
+    "fieldTypeCd": "currency",
+    "baseDatatypeCd": "number",
+    "flags": "V",
+    "orderNum": 60,
+    "formula": "[quantity] * [unit_price]",
+    "description": "Line Total"
+}
+```
+
+### Customer country (via navigation)
+
+```json
+"customer_country": {
+    "columnType": "F",
+    "fieldTypeCd": "text",
+    "baseDatatypeCd": "string",
+    "flags": "V",
+    "orderNum": 70,
+    "formula": "[account].[billing_country]",
+    "description": "Customer Country"
+}
+```
+
+### Days since created
+
+```json
+"days_open": {
+    "columnType": "F",
+    "fieldTypeCd": "number",
+    "baseDatatypeCd": "number",
+    "flags": "V",
+    "orderNum": 200,
+    "formula": "DATEDIFF([created_date], NOW(), 'day')",
+    "description": "Days Open"
+}
+```
+
+## Common mistakes
+
+- Using `column_name` without brackets — **wrong**. Always `[column_name]`.
+- Inventing functions like `HAS_PERMISSION()`, `IS_ADMIN()`, `GET_USER()` — **do not exist**. Do not use unless confirmed to exist in the actual dForge engine.
+- Using JavaScript syntax like `row.field` or `this.field` — **wrong**. Only `[field]`.
+- Forgetting `baseDatatypeCd` on formula columns — **required**. Without it, filters and SQL don't work.
+- Using SQL syntax like `SELECT`, `JOIN`, `WHERE` — **wrong**. Formulas are expressions, not queries.
+- String concatenation with commas — **wrong**. Use `+` or `CONCAT()`.
+
+## Reference
+
+This file covers the most common formula functions and patterns. If you encounter an edge case not covered here, ask the user to check their dForge version's formula documentation.