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

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

@@ -0,0 +1,331 @@
+# Schema Import Reference
+
+When the user provides an existing database schema (DBML file, SQL DDL, or a description of their current tables), convert it into a dForge module. This is one of the most valuable things you can do — it turns hours of manual work into a few minutes of conversation.
+
+## Supported inputs
+
+| Input | How to handle |
+|---|---|
+| `.dbml` file | Parse the DBML syntax directly — tables, columns, refs, enums, notes |
+| `.sql` file (DDL) | Parse `CREATE TABLE`, `FOREIGN KEY`, `CHECK`, `UNIQUE`, column types, comments |
+| Pasted table description | Treat as informal spec, ask clarifying questions |
+| ERD image / diagram | Describe what you see and confirm with the user |
+
+## Conversion process
+
+### Step 1: Identify entities
+
+Each table in the source becomes a dForge entity. Apply naming conventions:
+
+- Table name → entity `dbObject` (lowercase `snake_case`, singular)
+- `CUSTOMERS` → `customer`, `tbl_OrderLines` → `order_line`
+- Ask the user if naming is ambiguous
+
+### Step 2: Map columns
+
+For each column, determine `fieldTypeCd`, `baseDatatypeCd`, `dbDatatype`, `flags`, and params.
+
+> **The source SQL type is authoritative — always map from it, never from the column name alone.** A column named `floor`, `level`, `count`, `code` could be an integer or a string; only the source type tells you which. Using the wrong `dbDatatype` causes `ENTITY_COLUMN_IMPORT_ERROR` type-mismatch on install. Name heuristics in the table below are secondary signals applied only when no source type is available (e.g. pasted informal descriptions).
+
+**Type mapping table:**
+
+| Source type | `fieldTypeCd` | `baseDatatypeCd` | `dbDatatype` | Notes |
+|---|---|---|---|---|
+| `varchar(n)`, `char(n)`, `text` | `text` | `string` | `varchar` | Set `maxLen` from `n` |
+| Column named `*email*` | `email` | `string` | `varchar` | Name heuristic |
+| Column named `*phone*`, `*tel*`, `*mobile*` | `phone` | `string` | `varchar` | Name heuristic |
+| Column named `*url*`, `*website*` | `url` | `string` | `varchar` | Name heuristic |
+| `text` (large / multiline context) | `textarea` | `string` | `text` | |
+| `int`, `integer`, `int4`, `smallint` | `number` | `number` | `int` | |
+| `bigint`, `int8` | `number` | `number` | `bigint` | |
+| `numeric(p,s)`, `decimal(p,s)` | `number` | `number` | `numeric` | Set `params.scale` |
+| Column named `*price*`, `*amount*`, `*cost*`, `*total*` | `currency` | `number` | `numeric` | Ask user for currency code |
+| `numeric` with CHECK `>= 0 AND <= 100` | `percent` | `number` | `numeric` | |
+| `boolean`, `bool`, `bit` | `checkbox` | `bool` | `bool` | |
+| `date` | `date` | `date` | `date` | |
+| `timestamp`, `timestamptz`, `datetime` | `datetime` | `timestamp` | `timestamptz` | |
+| `time` | `time` | `time` | `time` | |
+| `json`, `jsonb` | `json` | `json` | `jsonb` | |
+| `uuid` (non-PK, non-FK) | `text` | `string` | `varchar` | |
+| `bytea`, `blob` | `file` | `binary` | — | Best guess, confirm with user |
+| DBML `enum` | `dropdown` | `string` | `varchar` | Extract values to `params.options` |
+| `varchar` with `CHECK IN (…)` | `dropdown` | `string` | `varchar` | Extract to `params.options` |
+
+### Step 3: Detect audit columns → traits
+
+Look for common audit column patterns and replace them with traits:
+
+| Source columns | Replace with |
+|---|---|
+| `created_at` + `updated_at` (timestamps only) | `traits: ["audit"]` — remove those columns from `fields` |
+| `created_at` + `created_by` + `updated_at` + `updated_by` | `traits: ["audit-full"]` — remove all four |
+| `created_date` + `last_updated` | `traits: ["audit"]` — remove both |
+| `deleted_at` or `is_active` / `active` (soft delete) | Add `"soft-delete"` to traits |
+| `sort_order` / `order_num` / `display_order` | Add `"sorting"` to traits |
+
+If the source uses non-standard audit column names (e.g. `date_created`, `modified_by_user`), still convert them to traits and note the mapping.
+
+### Step 4: Detect PKs → identity trait
+
+| Source PK | Action |
+|---|---|
+| Single column `id`, `{table}_id` (integer or uuid) | Use `traits: ["identity"]` — don't declare the PK column manually |
+| Composite PK (two+ columns) | Declare each column with `"isPk": true`, don't use `identity` trait |
+| `uuid` PK with default `gen_random_uuid()` | Use `traits: ["identity"]` (dForge uses cuid, similar concept) |
+
+### Step 5: Map relationships → FK+Reference pattern
+
+**Explicit foreign keys** (DBML `Ref:` or SQL `FOREIGN KEY`):
+
+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`
+
+Plus declare the constraint in the entity's `references` block.
+
+**Implicit foreign keys** (column named `*_id` with no explicit FK):
+
+Look for tables that match the prefix. If `customer_id` exists and a `customer` table exists → probably a FK. Create the reference pair but **ask the user to confirm** ambiguous cases.
+
+### Step 6: Detect small lookup tables → dropdown options
+
+Tables with 2-3 columns, < 20 rows, and a simple `id + name` shape are likely enums, not real entities. Examples: `statuses`, `categories`, `priorities`, `types`.
+
+When detected:
+
+- **Option A**: Convert to a `dropdown` column with `params.options` on the referencing entity. Remove the lookup table entirely.
+- **Option B**: Keep as a real entity with a reference column.
+
+**Ask the user** which approach they prefer. Default to Option B (keep the entity) for safety.
+
+### Step 7: Generate the module
+
+Using the converted entities, generate the full module package:
+
+1. **`manifest.json`** — with `version: "0.1.0"`, `dbSchemaVersion: "0.0.1"`, entity list, dependencies (`admin`)
+2. **`entities/*.json`** — one per entity, with traits, fields, references
+3. **`ui/data_views.json`** — one grid view per entity with the first ~8 visible columns
+4. **`ui/menus.json`** — grouped logically (group related entities under section nodes)
+5. **`ui/folders.json`** — root folder with all entities listed
+6. **`security/roles.json`** — at least `module.admin` (SIUDC on everything) and `module.user` (SIU on main entities)
+7. **`translations/en-US.json`** — labels for all entities, fields, views, menus, actions, roles, folders
+8. **`seed-data/`** — if the source had enum/lookup tables converted to entities, generate seed data for them
+
+### Step 8: Generate IMPORT_NOTES.md
+
+List everything you couldn't convert automatically:
+
+```markdown
+# Import Notes
+
+Imported from: [source file name]
+Date: [date]
+Source: [N] tables, [N] columns, [N] foreign keys
+
+## Converted
+- [list of entities created]
+
+## Decisions made
+- `statuses` table converted to dropdown options on `order.status` column
+- `created_at`/`updated_at` replaced with `audit` trait
+- [etc.]
+
+## Not converted — manual work needed
+- View `v_customer_summary` — consider as a dForge report or formula column
+- Stored procedure `sp_calculate_totals` — convert to a DSL action
+- Trigger `trg_update_stock` — convert to a DSL action
+- Index `idx_customer_email` — dForge generates indexes from column flags
+
+## Questions for review
+- Is `credit_limit` a currency field? (mapped as `number` — change to `currency` if monetary)
+- Column `type` on `order` table — should this be a dropdown with fixed options or a free-text field?
+```
+
+## Example: DBML to dForge
+
+### Input (DBML)
+
+```dbml
+Table customers {
+  id integer [pk, increment]
+  name varchar(200) [not null]
+  email varchar(250)
+  phone varchar(50)
+  created_at timestamp [default: `now()`]
+  updated_at timestamp [default: `now()`]
+}
+
+Table orders {
+  id integer [pk, increment]
+  customer_id integer [not null, ref: > customers.id]
+  order_date date [not null]
+  status varchar(20) [not null, note: 'new, processing, shipped, delivered, cancelled']
+  total_amount decimal(10,2)
+  notes text
+  created_at timestamp [default: `now()`]
+  updated_at timestamp [default: `now()`]
+}
+
+Table order_lines {
+  id integer [pk, increment]
+  order_id integer [not null, ref: > orders.id]
+  product_name varchar(200) [not null]
+  quantity integer [not null]
+  unit_price decimal(10,2) [not null]
+}
+```
+
+### Output: `entities/customer.json`
+
+```json
+{
+    "description": "Customers",
+    "dbObject": "customer",
+    "toString": "{name}",
+    "traits": ["identity", "audit"],
+    "fields": {
+        "name": {
+            "dbDatatype": "varchar",
+            "fieldTypeCd": "text",
+            "flags": "VEM",
+            "maxLen": 200,
+            "orderNum": 10,
+            "description": "Customer Name"
+        },
+        "email": {
+            "dbDatatype": "varchar",
+            "fieldTypeCd": "email",
+            "flags": "VE",
+            "maxLen": 250,
+            "orderNum": 20,
+            "description": "Email"
+        },
+        "phone": {
+            "dbDatatype": "varchar",
+            "fieldTypeCd": "phone",
+            "flags": "VE",
+            "maxLen": 50,
+            "orderNum": 30,
+            "description": "Phone"
+        },
+        "orders": {
+            "columnType": "S",
+            "fieldTypeCd": "grid",
+            "flags": "VE",
+            "orderNum": 100,
+            "description": "Orders",
+            "link": {
+                "entity": "order",
+                "thisKey": "customer_id",
+                "otherKey": "customer_id"
+            }
+        }
+    }
+}
+```
+
+### Output: `entities/order.json`
+
+```json
+{
+    "description": "Orders",
+    "dbObject": "order",
+    "toString": "Order #{order_id}",
+    "traits": ["identity", "audit"],
+    "fields": {
+        "customer_id": {
+            "dbDatatype": "cuid",
+            "flags": "EM",
+            "orderNum": 10,
+            "description": "Customer ID"
+        },
+        "customer": {
+            "columnType": "R",
+            "fieldTypeCd": "lookup",
+            "flags": "VEM",
+            "orderNum": 15,
+            "description": "Customer",
+            "link": {
+                "entity": "customer",
+                "thisKey": "customer_id",
+                "otherKey": "customer_id"
+            }
+        },
+        "order_date": {
+            "dbDatatype": "date",
+            "fieldTypeCd": "date",
+            "flags": "VEM",
+            "orderNum": 20,
+            "description": "Order Date"
+        },
+        "status": {
+            "dbDatatype": "varchar",
+            "fieldTypeCd": "dropdown",
+            "flags": "VEM",
+            "maxLen": 20,
+            "orderNum": 30,
+            "description": "Status",
+            "params": {
+                "options": [
+                    { "value": "new", "label": "New" },
+                    { "value": "processing", "label": "Processing" },
+                    { "value": "shipped", "label": "Shipped" },
+                    { "value": "delivered", "label": "Delivered" },
+                    { "value": "cancelled", "label": "Cancelled" }
+                ]
+            }
+        },
+        "total_amount": {
+            "dbDatatype": "numeric",
+            "fieldTypeCd": "currency",
+            "flags": "VE",
+            "orderNum": 40,
+            "description": "Total Amount"
+        },
+        "notes": {
+            "dbDatatype": "text",
+            "fieldTypeCd": "textarea",
+            "flags": "VE",
+            "orderNum": 50,
+            "description": "Notes"
+        },
+        "lines": {
+            "columnType": "S",
+            "fieldTypeCd": "grid",
+            "flags": "VE",
+            "orderNum": 100,
+            "description": "Order Lines",
+            "link": {
+                "entity": "order_line",
+                "thisKey": "order_id",
+                "otherKey": "order_id"
+            }
+        }
+    },
+    "references": {
+        "FK_Order_Customer": {
+            "from": { "field": "customer_id" },
+            "to": { "entity": "customer", "field": "customer_id" }
+        }
+    }
+}
+```
+
+Note how:
+- Source `id` columns → replaced by `identity` trait
+- Source `created_at`/`updated_at` → replaced by `audit` trait
+- Source `customer_id` FK → FK+Reference pair (hidden `customer_id` + visible `customer` lookup)
+- Source `status` with note listing values → `dropdown` with `params.options`
+- Source `total_amount decimal(10,2)` → `currency` (inferred from name)
+- Parent `customers` gets a `orders` set column (backwards reference)
+- PK type changes from `integer` to `cuid` (dForge's native PK type via `identity` trait)
+
+## Tips
+
+- **Always ask about ambiguous columns** rather than guessing. "Is `credit_limit` currency? Is `type` a dropdown or free text?"
+- **Generate `IMPORT_NOTES.md`** with every schema import — the user needs to know what wasn't converted.
+- **Start with the most referenced entities** (parents) and work down to detail/line entities.
+- **Source PKs change type.** dForge uses `cuid` for PKs (via `identity` trait). The old integer PKs don't carry over. If the user later needs to migrate data, the migration script handles PK mapping (see `references/data-migration.md`).
+- **Preserve source column names** as `dbObject` / column codes where possible — this makes data migration easier later.
+- **Views, stored procedures, and triggers** cannot be converted automatically. List them in `IMPORT_NOTES.md` and offer to convert them one by one to dForge constructs (reports, actions, formulas).

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

@@ -0,0 +1,244 @@
+# Security Reference
+
+dForge has a **3-layer additive security model**:
+
+1. **Row-level** — folders define SQL WHERE filters
+2. **Column-level** — entity views control field visibility/editability
+3. **Operation-level** — roles grant entity rights (S/I/U/D/C) and object access (E)
+
+Roles are **additive** — a user with multiple roles gets the union of all their rights. Rights are never revoked by another role, only added.
+
+Roles are **folder-scoped** — the same role can have different effective rights in different folders, because folders define the row filter.
+
+Lives in: `security/roles.json`
+
+## Role definition
+
+Role codes use a `module.role` naming pattern (e.g. `crm.admin`, `crm.sales-rep`):
+
+```json
+{
+    "crm.admin": {
+        "description": "CRM Administrator",
+        "rights": {
+            "account":      "SIUDC",
+            "contact":      "SIUDC",
+            "lead":         "SIUDC",
+            "opportunity":  "SIUDC",
+            "opportunity_line": "SIUDC",
+            "product":      "SIUDC",
+            "quote":        "SIUDC",
+            "activity":     "SIUDC"
+        }
+    },
+    "crm.sales-rep": {
+        "description": "Sales Representative",
+        "rights": {
+            "account":      "SIUC",
+            "contact":      "SIUC",
+            "lead":         "SIUDC",
+            "opportunity":  "SIUC",
+            "opportunity_line": "SIUC",
+            "product":      "S",
+            "quote":        "SIUC",
+            "activity":     "SIUDC"
+        }
+    },
+    "crm.viewer": {
+        "description": "CRM Viewer (Read-Only)",
+        "rights": {
+            "account": "S",
+            "contact": "S",
+            "lead": "S",
+            "opportunity": "S",
+            "product": "S",
+            "quote": "S",
+            "activity": "S"
+        }
+    }
+}
+```
+
+## Rights letters
+
+### Entity rights (on entity codes)
+
+| Letter | Permission |
+|---|---|
+| `S` | Select (read rows) |
+| `I` | Insert (create rows) |
+| `U` | Update (modify rows) |
+| `D` | Delete (remove rows) |
+| `C` | Clone (duplicate a row as a new record) |
+
+### Action/Report/Folder rights
+
+| Letter | Permission |
+|---|---|
+| `E` | Execute (run the action/report, access the folder) |
+
+### Common combinations
+
+| Rights | Meaning |
+|---|---|
+| `"S"` | Read only |
+| `"SI"` | Read + create, no modify/delete |
+| `"SIU"` | Read/write, no delete |
+| `"SIUD"` | Full CRUD (most common for primary roles) |
+| `"SIUDC"` | Full CRUD + clone |
+| `"E"` | Execute (actions/reports/folders) |
+
+## Object references
+
+Role rights map object codes (entities, actions, reports) to rights strings. Object codes are:
+
+- `contact` — the entity named "contact" in this module (bare, same-module)
+- `fin.invoice` — the entity "invoice" in the `fin` module (cross-module entity — **dot**)
+- `action:send_welcome` — an action named "send_welcome" (**colon**)
+- `report:sales_pipeline` — a report named "sales_pipeline" (**colon**)
+- `folder:customers` — the folder with code "customers" (**colon**)
+
+> **Separator matters — colon for non-entity objects, dot only for cross-module entities.**
+> Actions, reports and folders are prefixed with a **colon**: `action:<code>`, `report:<code>`,
+> `folder:<code>`. A **dot** is reserved for a cross-module *entity* (`module.entity`, e.g.
+> `parties.party`). Writing `action.send_welcome` (dot) is **wrong** — the installer treats it as
+> entity `send_welcome` in a module named `action`, finds nothing, and rejects the grant as an
+> unknown object. Same-module entities are bare (`contact`). This matches every dForge-core
+> module (`"action:submit_po": "E"`).
+
+## Rules
+
+1. **Use `"rights"`**, never `"entityRights"` (the wrong name is the most common mistake).
+2. **Every module should define at least one role.** Without roles, tenant admins can't grant access to anyone.
+3. **Create multiple roles for different user personas** — e.g. `sales_rep`, `sales_admin`, `sales_manager`.
+4. **Never grant `D` (Delete) to a rep-level role** unless deletion is a normal part of their job. Audit trails prefer soft-delete or update.
+5. **Always grant the admin role `SIUDC` on everything the module owns.**
+6. **Action and report access** — grant `E` on specific action/report codes, or omit them entirely (defaulting to no access).
+7. **Folder access** is granted separately — roles can reference folder codes, but folder definitions themselves live in `ui/folders.json`.
+
+## Folders (`ui/folders.json`)
+
+Folders define the **folder tree** created when the module is installed. They declare which entities are available, default views, quick-add, and optionally **row-level filtering** and **subfolders**.
+
+Lives in: `ui/folders.json`
+
+### Simple example (CRM — flat, no subfolders)
+
+```json
+{
+    "label": "Sales CRM",
+    "description": "Customer relationship management and sales pipeline",
+    "color": "#2196F3",
+    "entities": {
+        "account": { "viewName": "default", "quickAdd": true },
+        "contact": { "viewName": "default", "quickAdd": true },
+        "opportunity": { "viewName": "default", "quickAdd": true },
+        "opportunity_line": { "viewName": "default", "quickAdd": false },
+        "product": { "viewName": "default", "quickAdd": true }
+    }
+}
+```
+
+### Advanced example (WMS — subfolders with row filters)
+
+```json
+{
+    "label": "Warehouse Management",
+    "description": "Inventory, purchasing, and warehouse operations",
+    "color": "#FF9800",
+    "entities": {
+        "warehouse": { "viewName": "default", "quickAdd": true },
+        "product": { "viewName": "default", "quickAdd": true },
+        "stock": { "viewName": "default", "quickAdd": true },
+        "stock_movement": { "viewName": "default", "quickAdd": true },
+        "purchase_order": { "viewName": "default", "quickAdd": true },
+        "purchase_order_line": { "viewName": "default", "quickAdd": false }
+    },
+    "children": {
+        "central": {
+            "label": "Central Warehouse",
+            "description": "Main distribution center",
+            "color": "#2196F3",
+            "inheritSecurity": true,
+            "entities": {
+                "stock": {
+                    "viewName": "default",
+                    "quickAdd": true,
+                    "rowFilter": { "c": "warehouse_id", "o": "eq", "v": 2001 }
+                },
+                "stock_movement": {
+                    "viewName": "default",
+                    "quickAdd": true,
+                    "rowFilter": { "c": "warehouse_id", "o": "eq", "v": 2001 }
+                },
+                "purchase_order": {
+                    "viewName": "default",
+                    "quickAdd": true,
+                    "rowFilter": { "c": "warehouse_id", "o": "eq", "v": 2001 }
+                }
+            }
+        },
+        "east": {
+            "label": "East Warehouse",
+            "color": "#4CAF50",
+            "inheritSecurity": true,
+            "entities": {
+                "stock": {
+                    "viewName": "default",
+                    "quickAdd": true,
+                    "rowFilter": { "c": "warehouse_id", "o": "eq", "v": 2002 }
+                }
+            }
+        }
+    }
+}
+```
+
+### Folder properties
+
+| Property | Type | Description |
+|---|---|---|
+| `label` | string | Display name in sidebar |
+| `description` | string | Shown in folder header |
+| `color` | string | Hex accent color |
+| `entities` | object | Entity membership (see below) |
+| `children` | object | Subfolder definitions (same shape recursively) |
+| `inheritSecurity` | boolean | Child inherits parent folder's role assignments |
+
+### Entity membership properties
+
+| Property | Type | Description |
+|---|---|---|
+| `viewName` | string | Default data view (usually `"default"`) |
+| `quickAdd` | boolean | Show "+" quick-add button (`true` for main entities, `false` for detail/line items) |
+| `rowFilter` | object | Row-level filter scoping which records are visible in this folder |
+
+### Row filters (`rowFilter`)
+
+Row filters use a compact filter object with:
+- `c` — column code to filter on
+- `o` — operator (`eq`, `neq`, `gt`, `lt`, `gte`, `lte`, `in`, `not_in`, etc.)
+- `v` — value to compare against
+
+This is how **row-level security** works in the module package — subfolders with `rowFilter` restrict which rows are visible. Users assigned to "Central Warehouse" only see stock where `warehouse_id = 2001`.
+
+### When to use subfolders
+
+- **Multi-location modules** (warehouses, offices, branches) — one subfolder per location, filtered by location FK
+- **Multi-department modules** — one subfolder per department
+- **Regional access** — filter by region/country column
+
+For simple modules, a flat root folder (no `children`) is fine — just `label`, `color`, and `entities`.
+
+## Common mistakes
+
+- Using `"entityRights"` instead of `"rights"` — **wrong**.
+- Using a **dot** for an action/report/folder (`action.send_welcome`) — **wrong**. Use a **colon**: `action:send_welcome`, `report:...`, `folder:...`. A dot is only for cross-module *entities* (`fin.invoice`).
+- Granting a bare action code (`send_welcome` with no prefix) — **wrong**, it's read as an entity and rejected as unknown. Prefix it: `action:send_welcome`.
+- Mapping an object to an empty rights string (`"action:x": ""`) — **wrong**. To deny, **omit** the key entirely; to grant, use `"E"`.
+- Using long names like `"read,write"` instead of `"SIU"` — **wrong**.
+- Forgetting to define any role — module installs but no user can access anything.
+- Granting `"D"` casually — delete should be rare.
+- Trying to **revoke** rights with a second role — impossible. Rights are additive only.
+- Inventing rights letters like `"R"` for read or `"W"` for write — **wrong**. Use `SIUD`.
+- Putting folders in `security/` — **wrong**. It's `ui/folders.json`.