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

package/skills/dforge-mcp-author/examples/matrix-budget/README.md

@@ -0,0 +1,43 @@
+# matrix-budget — matrix (pivot) view example
+
+A minimal module whose only job is to demonstrate the `matrix` data view. The
+simple-todo example has no cross-tab domain, so the matrix shape lives here.
+
+## The shape
+
+A matrix view is `rowAxis × colAxis` with a **cell** entity holding one record
+per intersection. Here:
+
+| Piece | Maps to |
+|---|---|
+| `rowAxis` | `budget_category` records (a **dataset** axis), labelled by `name`, sorted by `code` |
+| `colAxis` | the `quarter` dropdown options Q1–Q4 (a **dropdown** axis: `"budget_line.quarter"`) |
+| `cell` | a `budget_line` record per (category, quarter); the editable value is `amount` |
+
+So the grid reads: budget categories down the side, quarters across the top,
+an editable amount in each cell.
+
+## What it illustrates
+
+- **Two axis kinds in one view** — a `dataset` row axis and a `dropdown` column
+  axis (the only worked example of the dropdown axis).
+- **Editable cells** (`cell.editable: true`) — typing in an empty cell inserts a
+  `budget_line`; the matrix fills `rowKey` (`category_id`) and `colKey`
+  (`quarter`) automatically from the row/column it sits in.
+- The **cell entity is the view's primary `dataSources` entity**, and
+  `cell.rowKey` / `cell.colKey` are real columns on it.
+
+For a read-only `dataset × dataset` matrix (P&L: accounts × periods) plus the
+`date` axis and the `lockedField` / `drill` / `seedFromRow` options, see the
+§Matrix section of `dforge://reference/data-views`.
+
+## Files
+
+```
+manifest.json
+entities/budget_category.json   row-axis (dataset) entity
+entities/budget_line.json       cell entity (FK+Reference + quarter dropdown + amount)
+ui/data_views.json              the matrix view (+ a categories grid)
+security/roles.json             S on the axis, SIUD on the editable cell
+seed-data/01-categories.json    three categories to populate the rows
+```

package/skills/dforge-mcp-author/examples/matrix-budget/entities/budget_category.json

@@ -0,0 +1,24 @@
+{
+	"description": "Budget categories — the row axis of the budget matrix",
+	"dbObject": "budget_category",
+	"toString": "{name}",
+	"traits": ["identity", "audit"],
+	"fields": {
+		"code": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "text",
+			"flags": "VEM",
+			"maxLen": 20,
+			"orderNum": 10,
+			"description": "Code"
+		},
+		"name": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "text",
+			"flags": "VEM",
+			"maxLen": 100,
+			"orderNum": 20,
+			"description": "Name"
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/matrix-budget/entities/budget_line.json

@@ -0,0 +1,56 @@
+{
+	"description": "Budget lines — the value-source CELL entity. One row per (category, quarter); the matrix edits the amount in place.",
+	"dbObject": "budget_line",
+	"toString": "{category} {quarter}",
+	"traits": ["identity", "audit"],
+	"fields": {
+		"category_id": {
+			"dbDatatype": "cuid",
+			"flags": "EM",
+			"orderNum": 10,
+			"description": "Category ID"
+		},
+		"category": {
+			"columnType": "R",
+			"fieldTypeCd": "lookup",
+			"flags": "VEM",
+			"orderNum": 15,
+			"description": "Category",
+			"link": {
+				"entity": "budget_category",
+				"thisKey": "category_id",
+				"otherKey": "budget_category_id"
+			}
+		},
+		"quarter": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "dropdown",
+			"flags": "VEM",
+			"maxLen": 2,
+			"orderNum": 20,
+			"description": "Quarter",
+			"params": {
+				"options": [
+					{ "value": "Q1", "label": "Q1" },
+					{ "value": "Q2", "label": "Q2" },
+					{ "value": "Q3", "label": "Q3" },
+					{ "value": "Q4", "label": "Q4" }
+				]
+			}
+		},
+		"amount": {
+			"dbDatatype": "numeric",
+			"fieldTypeCd": "number",
+			"flags": "VEM",
+			"orderNum": 30,
+			"description": "Amount",
+			"params": { "min": 0 }
+		}
+	},
+	"references": {
+		"FK_BudgetLine_Category": {
+			"from": { "field": "category_id" },
+			"to": { "entity": "budget_category", "field": "budget_category_id" }
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/matrix-budget/manifest.json

@@ -0,0 +1,30 @@
+{
+	"packageFormat": 1,
+	"moduleId": "20000000-0000-0000-0000-000000000002",
+	"code": "matrix_budget",
+	"version": "0.1.0",
+	"dbSchemaVersion": "0.0.1",
+	"displayName": "Matrix Budget",
+	"description": "Minimal example demonstrating a matrix (pivot) data view: dataset row axis × dropdown column axis with editable cells",
+	"author": { "name": "dForge Examples" },
+	"license": "MIT",
+	"category": "Examples",
+	"tags": ["example", "matrix", "budget"],
+	"icon": "bi-grid-3x3",
+	"dependencies": {
+		"admin": ">=0.0.1"
+	},
+	"created": "2026-06-25",
+	"updated": "2026-06-25",
+	"entities": {
+		"budget_category": "./entities/budget_category.json",
+		"budget_line": "./entities/budget_line.json"
+	},
+	"dataViews": "./ui/data_views.json",
+	"security": {
+		"roles": "./security/roles.json"
+	},
+	"seedData": [
+		"./seed-data/01-categories.json"
+	]
+}

package/skills/dforge-mcp-author/examples/matrix-budget/security/roles.json

@@ -0,0 +1,9 @@
+{
+	"matrix_budget.user": {
+		"description": "Can view categories and edit budget amounts in the matrix",
+		"rights": {
+			"budget_category": "S",
+			"budget_line": "SIUD"
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/matrix-budget/seed-data/01-categories.json

@@ -0,0 +1,8 @@
+{
+	"entityCode": "budget_category",
+	"records": [
+		{ "budget_category_id": 2001, "code": "REV", "name": "Revenue" },
+		{ "budget_category_id": 2002, "code": "COGS", "name": "Cost of Goods Sold" },
+		{ "budget_category_id": 2003, "code": "OPEX", "name": "Operating Expenses" }
+	]
+}

package/skills/dforge-mcp-author/examples/matrix-budget/ui/data_views.json

@@ -0,0 +1,42 @@
+{
+	"budget_matrix": {
+		"viewType": "matrix",
+		"label": "Budget (Category × Quarter)",
+		"description": "Editable budget: categories down the side, quarters across the top, the amount edited in each cell.",
+		"dataSources": [{
+			"entityCode": "budget_line",
+			"columns": ["category_id", "quarter", "amount"]
+		}],
+		"viewConfig": {
+			"rowAxis": {
+				"kind": "dataset",
+				"entity": "budget_category",
+				"labelField": "name",
+				"sort": [{ "col": "code", "dir": "asc" }]
+			},
+			"colAxis": {
+				"kind": "dropdown",
+				"column": "budget_line.quarter"
+			},
+			"cell": {
+				"entity": "budget_line",
+				"rowKey": "category_id",
+				"colKey": "quarter",
+				"fields": ["amount"],
+				"editable": true
+			}
+		}
+	},
+	"budget_categories_grid": {
+		"label": "Categories",
+		"icon": "bi-tags",
+		"dataSources": [{
+			"entityCode": "budget_category",
+			"columns": [
+				{ "column_cd": "code", "width": 100 },
+				{ "column_cd": "name", "width": 300 }
+			],
+			"order": ["code"]
+		}]
+	}
+}

package/skills/dforge-mcp-author/examples/simple-todo/README.md

@@ -0,0 +1,38 @@
+# Simple Todo — Example Module
+
+A minimal but complete dForge module. Use it as a reference for:
+
+- Module package layout
+- Entity definition with traits, columns, and a reference
+- Data view with a grid
+- Menu with a single leaf item
+- Security role with full CRUD
+- Seed data with numbered files
+- A simple DSL action (mark as done)
+
+**Not meant for production** — it's a teaching example.
+
+## What it contains
+
+| File | Purpose |
+|---|---|
+| `manifest.json` | Module metadata and file listing |
+| `entities/todo_list.json` | Lists that group todos |
+| `entities/todo_item.json` | Individual todo items, with reference to list |
+| `ui/data_views.json` | Two grid views — one for lists, one for items |
+| `ui/menus.json` | Nested menu with "Lists" and "Items" |
+| `ui/actions.json` | Registers the mark-done action |
+| `logic/actions/mark_done.dsl` | The action DSL |
+| `security/roles.json` | `todo_user` role with full CRUD |
+| `seed-data/01-lists.json` | Two seed lists |
+
+## Key patterns demonstrated
+
+1. **FK+Reference pattern** — `todo_item` has `list_id` (hidden FK) + `list` (visible Reference)
+2. **Traits** — both entities use `["identity", "audit"]`
+3. **toString** — `todo_list` uses `{name}`, `todo_item` uses `{title}`
+4. **`dataSources` array** in data views (never root-level `entityCode`)
+5. **Nested dict menus** with `dataViewCode` on leaves
+6. **`rights` (not `entityRights`)** in roles
+7. **Numbered seed files** for FK ordering
+8. **DSL action** with `canExecute:` gating on `[done] == false`

package/skills/dforge-mcp-author/examples/simple-todo/entities/todo_item.json

@@ -0,0 +1,83 @@
+{
+	"description": "Individual todo items",
+	"dbObject": "todo_item",
+	"toString": "{title}",
+	"traits": ["identity", "audit"],
+	"fields": {
+		"title": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "text",
+			"flags": "VEM",
+			"maxLen": 200,
+			"orderNum": 10,
+			"description": "Title"
+		},
+		"description": {
+			"dbDatatype": "text",
+			"fieldTypeCd": "textarea",
+			"flags": "VE",
+			"orderNum": 20,
+			"description": "Description"
+		},
+		"priority": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "dropdown",
+			"flags": "VEM",
+			"maxLen": 20,
+			"orderNum": 30,
+			"description": "Priority",
+			"params": {
+				"options": [
+					{ "value": "low", "label": "Low", "color": "#6c757d" },
+					{ "value": "medium", "label": "Medium", "color": "#ffc107" },
+					{ "value": "high", "label": "High", "color": "#dc3545" }
+				]
+			}
+		},
+		"done": {
+			"dbDatatype": "bool",
+			"fieldTypeCd": "checkbox",
+			"flags": "VEM",
+			"formula": "false",
+			"orderNum": 40,
+			"description": "Done"
+		},
+		"due_date": {
+			"dbDatatype": "date",
+			"fieldTypeCd": "date",
+			"flags": "VE",
+			"orderNum": 50,
+			"description": "Due Date"
+		},
+		"list_id": {
+			"dbDatatype": "cuid",
+			"flags": "EM",
+			"orderNum": 60,
+			"description": "List ID"
+		},
+		"list": {
+			"columnType": "R",
+			"fieldTypeCd": "lookup",
+			"flags": "VEM",
+			"orderNum": 65,
+			"description": "List",
+			"link": {
+				"entity": "todo_list",
+				"thisKey": "list_id",
+				"otherKey": "todo_list_id"
+			}
+		},
+		"owner_id": {
+			"fieldTypeCd": "user",
+			"flags": "VE",
+			"orderNum": 70,
+			"description": "Assigned To"
+		}
+	},
+	"references": {
+		"FK_TodoItem_List": {
+			"from": { "field": "list_id" },
+			"to": { "entity": "todo_list", "field": "todo_list_id" }
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/simple-todo/entities/todo_list.json

@@ -0,0 +1,43 @@
+{
+	"description": "Lists that group todo items",
+	"dbObject": "todo_list",
+	"toString": "{name}",
+	"traits": ["identity", "audit"],
+	"fields": {
+		"name": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "text",
+			"flags": "VEM",
+			"maxLen": 100,
+			"orderNum": 10,
+			"description": "List Name"
+		},
+		"color": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "color",
+			"flags": "VEM",
+			"maxLen": 20,
+			"orderNum": 20,
+			"description": "Color"
+		},
+		"description": {
+			"dbDatatype": "text",
+			"fieldTypeCd": "textarea",
+			"flags": "VE",
+			"orderNum": 30,
+			"description": "Notes"
+		},
+		"items": {
+			"columnType": "S",
+			"fieldTypeCd": "grid",
+			"flags": "VEM",
+			"orderNum": 100,
+			"description": "Items",
+			"link": {
+				"entity": "todo_item",
+				"thisKey": "todo_list_id",
+				"otherKey": "list_id"
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/simple-todo/logic/actions/mark_done.dsl

@@ -0,0 +1,6 @@
+canExecute:
+	[done] = false
+
+execute:
+	[done] = true
+	info('Marked as done')

package/skills/dforge-mcp-author/examples/simple-todo/manifest.json

@@ -0,0 +1,32 @@
+{
+	"packageFormat": 1,
+	"moduleId": "20000000-0000-0000-0000-000000000001",
+	"code": "simple_todo",
+	"version": "0.1.0",
+	"dbSchemaVersion": "0.0.1",
+	"displayName": "Simple Todo",
+	"description": "Minimal example module demonstrating the dForge package format",
+	"author": { "name": "dForge Examples" },
+	"license": "MIT",
+	"category": "Examples",
+	"tags": ["example", "todo"],
+	"icon": "bi-check-square",
+	"dependencies": {
+		"admin": ">=0.0.1"
+	},
+	"created": "2026-04-08",
+	"updated": "2026-04-08",
+	"entities": {
+		"todo_list": "./entities/todo_list.json",
+		"todo_item": "./entities/todo_item.json"
+	},
+	"dataViews": "./ui/data_views.json",
+	"menus": "./ui/menus.json",
+	"actions": "./ui/actions.json",
+	"security": {
+		"roles": "./security/roles.json"
+	},
+	"seedData": [
+		"./seed-data/01-lists.json"
+	]
+}

package/skills/dforge-mcp-author/examples/simple-todo/security/roles.json

@@ -0,0 +1,10 @@
+{
+	"simple_todo.user": {
+		"description": "Can manage their own todo lists and items",
+		"rights": {
+			"todo_list": "SIUDC",
+			"todo_item": "SIUDC",
+			"action:mark_done": "E"
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/simple-todo/seed-data/01-lists.json

@@ -0,0 +1,17 @@
+{
+	"entityCode": "todo_list",
+	"records": [
+		{
+			"todo_list_id": 1001,
+			"name": "Personal",
+			"color": "#4dabf7",
+			"description": "Personal tasks and errands"
+		},
+		{
+			"todo_list_id": 1002,
+			"name": "Work",
+			"color": "#51cf66",
+			"description": "Work-related tasks"
+		}
+	]
+}

package/skills/dforge-mcp-author/examples/simple-todo/ui/actions.json

@@ -0,0 +1,11 @@
+{
+	"mark_done": {
+		"label": "Mark Done",
+		"description": "Mark this todo item as completed",
+		"icon": "bi-check-circle",
+		"entityCode": "todo_item",
+		"executionMode": "each",
+		"script": "mark_done",
+		"isAsync": false
+	}
+}

package/skills/dforge-mcp-author/examples/simple-todo/ui/data_views.json

@@ -0,0 +1,35 @@
+{
+	"todo_list_grid": {
+		"label": "All Lists",
+		"description": "All todo lists",
+		"viewType": "grid",
+		"icon": "bi-list-ul",
+		"dataSources": [{
+			"entityCode": "todo_list",
+			"columns": [
+				{ "column_cd": "name", "width": 200 },
+				{ "column_cd": "color", "width": 80 },
+				{ "column_cd": "description", "width": 400 }
+			],
+			"order": ["name"]
+		}]
+	},
+	"todo_item_grid": {
+		"label": "All Items",
+		"description": "All todo items across all lists",
+		"viewType": "grid",
+		"icon": "bi-check-square",
+		"dataSources": [{
+			"entityCode": "todo_item",
+			"columns": [
+				{ "column_cd": "title", "width": 300 },
+				{ "column_cd": "list", "width": 150 },
+				{ "column_cd": "priority", "width": 100 },
+				{ "column_cd": "done", "width": 80 },
+				{ "column_cd": "due_date", "width": 120 },
+				{ "column_cd": "owner_id", "width": 150 }
+			],
+			"order": ["due_date"]
+		}]
+	}
+}

package/skills/dforge-mcp-author/examples/simple-todo/ui/menus.json

@@ -0,0 +1,28 @@
+{
+	"todo_menu": {
+		"label": "Todos",
+		"items": {
+			"lists": {
+				"orderNum": 1,
+				"label": "Lists & Items",
+				"icon": "check-square",
+				"children": {
+					"all_lists": {
+						"itemType": "V",
+						"label": "Lists",
+						"icon": "list-ul",
+						"dataViewCode": "todo_list_grid",
+						"orderNum": 1
+					},
+					"all_items": {
+						"itemType": "V",
+						"label": "All Items",
+						"icon": "check2-square",
+						"dataViewCode": "todo_item_grid",
+						"orderNum": 2
+					}
+				}
+			}
+		}
+	}
+}