@dforge-core/dforge-mcp 0.1.0-rc.1 → 0.1.0-rc.11

package/resources/schemas/reports.schema.json

@@ -0,0 +1,221 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/reports.schema.json",
+	"title": "dForge Module Reports",
+	"description": "Report definitions for a dForge module: a map of report code → report definition. Reports are not listed in manifest.json; the install pipeline picks up ui/reports.json automatically.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/report"
+	},
+	"$defs": {
+		"report": {
+			"type": "object",
+			"required": ["description", "layout", "datasets"],
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Human-readable report title"
+				},
+				"layout": {
+					"$ref": "#/$defs/layout"
+				},
+				"datasets": {
+					"type": "object",
+					"description": "Map of dataset code → dataset definition. Panels reference datasets by code via `datasetCd`.",
+					"additionalProperties": { "$ref": "#/$defs/dataset" }
+				},
+				"parameters": {
+					"type": "object",
+					"description": "Report-level parameters (alternative to per-dataset `params`). Map of param code → param definition.",
+					"additionalProperties": { "$ref": "#/$defs/paramDef" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"layout": {
+			"type": "object",
+			"required": ["panels"],
+			"properties": {
+				"panels": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/panel" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"panel": {
+			"type": "object",
+			"required": ["vizType", "datasetCd"],
+			"properties": {
+				"vizType": {
+					"type": "string",
+					"enum": ["table", "chart", "metric", "pivot"],
+					"description": "Visualization type"
+				},
+				"datasetCd": {
+					"type": "string",
+					"description": "Dataset code (key in the parent `datasets` map)"
+				},
+				"title": { "type": "string" },
+				"config": {
+					"type": "object",
+					"description": "Viz-type-specific configuration. For chart: { chartType, categoryCol, valueCol, agg, chartSize }. For table: { groupRules, aggregations }."
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"dataset": {
+			"type": "object",
+			"required": ["datasetType"],
+			"properties": {
+				"caption": {
+					"type": "string",
+					"description": "Display label for the dataset (used in panel headings if no `title`)"
+				},
+				"datasetType": {
+					"type": "string",
+					"enum": ["Q", "S"],
+					"description": "Q = SQL/entity query, S = stored procedure"
+				},
+				"query": {
+					"$ref": "#/$defs/query",
+					"description": "Used when datasetType is 'Q'"
+				},
+				"procedureName": {
+					"type": "string",
+					"description": "Used when datasetType is 'S'"
+				},
+				"columnsDef": {
+					"type": "object",
+					"description": "Optional column metadata overrides: field code → { label, visible, ... }",
+					"additionalProperties": { "$ref": "#/$defs/columnDef" }
+				},
+				"params": {
+					"type": "object",
+					"description": "Dataset-level parameters (alternative to top-level `parameters`)",
+					"additionalProperties": { "$ref": "#/$defs/paramDef" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"query": {
+			"type": "object",
+			"required": ["entityCd"],
+			"properties": {
+				"entityCd": {
+					"type": "string",
+					"description": "Source entity code"
+				},
+				"columns": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Column codes to select (supports dot navigation: 'customer.name')"
+				},
+				"filter": {
+					"$ref": "#/$defs/filter"
+				},
+				"sort": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/sortClause" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"sortClause": {
+			"type": "object",
+			"required": ["c"],
+			"properties": {
+				"c": { "type": "string", "description": "Column code" },
+				"d": {
+					"type": "string",
+					"enum": ["asc", "desc"],
+					"description": "Sort direction (default: asc)"
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"columnDef": {
+			"type": "object",
+			"properties": {
+				"label": { "type": "string" },
+				"visible": { "type": "boolean" },
+				"width": { "type": "integer", "minimum": 1 }
+			},
+			"additionalProperties": false
+		},
+
+		"paramDef": {
+			"type": "object",
+			"required": ["fieldTypeCd"],
+			"properties": {
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Field type code (see settings.schema.json for the common list)"
+				},
+				"label": { "type": "string" },
+				"required": {
+					"type": "boolean",
+					"default": false,
+					"description": "Whether the user must provide a value (older modules also use `isRequired`)"
+				},
+				"isRequired": {
+					"type": "boolean",
+					"description": "Alternate spelling of `required` used by some modules. Prefer `required` for new code."
+				},
+				"default": {
+					"description": "Default value applied if the user doesn't provide one"
+				},
+				"link": {
+					"type": "object",
+					"description": "Entity link for lookup-type params (alternative to nesting under `params.link`). Shape: { entity: '<code>', otherKey?: '<column>' }.",
+					"properties": {
+						"entity": { "type": "string" },
+						"otherKey": { "type": "string" }
+					},
+					"additionalProperties": false
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type-specific params (e.g. lookup → { link: { entity, otherKey } })"
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"filter": {
+			"description": "Canonical dForge filter expression — same shape as data_views.json filter. Either `{c, o, v}` or `{g, i: [...]}`.",
+			"oneOf": [
+				{ "$ref": "#/$defs/filterCondition" },
+				{ "$ref": "#/$defs/filterGroup" }
+			]
+		},
+		"filterCondition": {
+			"type": "object",
+			"required": ["c", "o"],
+			"properties": {
+				"c": { "type": "string" },
+				"o": { "type": "string" },
+				"v": {}
+			},
+			"additionalProperties": false
+		},
+		"filterGroup": {
+			"type": "object",
+			"required": ["g", "i"],
+			"properties": {
+				"g": { "type": "string", "enum": ["and", "or"] },
+				"i": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/filter" }
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/resources/schemas/roles.schema.json

@@ -0,0 +1,32 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/roles.schema.json",
+	"title": "dForge Roles",
+	"description": "Role definitions with entity rights for a dForge module",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/role"
+	},
+	"$defs": {
+		"role": {
+			"type": "object",
+			"required": ["description", "rights"],
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Role display name"
+				},
+				"rights": {
+					"type": "object",
+					"description": "Entity rights: entity code → rights string",
+					"additionalProperties": {
+						"type": "string",
+						"pattern": "^[SIUDCE]*$",
+						"description": "Rights: S=Select, I=Insert, U=Update, D=Delete, C=Clone, E=Execute"
+					}
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/resources/schemas/seed-data.schema.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/seed_data.schema.json",
+	"title": "dForge Seed Data",
+	"description": "Seed data records for a dForge entity",
+	"type": "object",
+	"required": ["entityCode", "records"],
+	"properties": {
+		"entityCode": {
+			"type": "string",
+			"description": "Target entity code to insert records into"
+		},
+		"records": {
+			"type": "array",
+			"description": "Array of records, each record is an object with column_code → value",
+			"items": {
+				"type": "object",
+				"additionalProperties": true
+			}
+		}
+	},
+	"additionalProperties": false
+}

package/resources/schemas/settings.schema.json

@@ -0,0 +1,55 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/settings.schema.json",
+	"title": "dForge Module Settings",
+	"description": "Module-level settings definitions: a flat map of setting code → setting definition. Settings are folder-scoped at runtime (values inherit through the folder tree) and surface in the Module Settings UI.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/setting"
+	},
+	"$defs": {
+		"setting": {
+			"type": "object",
+			"required": ["fieldTypeCd"],
+			"properties": {
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Field type code (must match one in dforge.field_type). Common values: text, number, integer, decimal, boolean, checkbox, dropdown, multiSelect, date, dateTime, time, image, file, fileList, lookup, color, currency, percent, html, markdown, password, email, phone, url, textarea, json."
+				},
+				"baseDatatypeCd": {
+					"type": "string",
+					"enum": ["string", "number", "bool", "date", "dateTime", "time", "json"],
+					"description": "Underlying primitive datatype. Older settings declare this explicitly; newer settings (using `formula`) often omit it."
+				},
+				"label": {
+					"type": "string",
+					"description": "Display label (newer style). Prefer this over `description`/`desc` for new settings."
+				},
+				"description": {
+					"type": "string",
+					"description": "Display label (older style). Use `label` for new settings."
+				},
+				"desc": {
+					"type": "string",
+					"description": "Alternative label key used by some older modules. Prefer `label`."
+				},
+				"defaultValue": {
+					"description": "Default value before the user sets one. Type matches `baseDatatypeCd`."
+				},
+				"formula": {
+					"type": "string",
+					"description": "Formula expression to evaluate the default (e.g. \"'USD'\"). Alternative to `defaultValue`."
+				},
+				"required": {
+					"type": "boolean",
+					"description": "If true, the setting must be set somewhere in the folder chain for installation to proceed."
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type-specific parameters. Examples: dropdown → { options: [...] }; number → { min, max }; lookup → { link: { entity, otherKey } }."
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/resources/schemas/traits.schema.json

@@ -0,0 +1,99 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/traits.schema.json",
+	"title": "dForge Trait Definitions",
+	"description": "Defines entity traits that expand into fields, references, and constraints during module install. Shipped as traits.json at module root.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/traitDefinition"
+	},
+	"$defs": {
+		"traitDefinition": {
+			"type": "object",
+			"description": "A single trait definition",
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Human-readable description of the trait"
+				},
+				"includes": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Other trait names to include (inherit fields from). Expanded recursively with circular reference protection."
+				},
+				"fields": {
+					"type": "object",
+					"description": "Field definitions to add to entities using this trait. Keys support {entity}/{Entity} placeholders for parametric names.",
+					"additionalProperties": {
+						"$ref": "#/$defs/traitField"
+					}
+				},
+				"references": {
+					"type": "object",
+					"description": "FK reference definitions to add. Keys support {Entity} placeholder.",
+					"additionalProperties": {
+						"$ref": "#/$defs/traitReference"
+					}
+				},
+				"constraints": {
+					"type": "object",
+					"description": "Constraint definitions to add. Keys support {Entity} placeholder (e.g. 'UQ_{Entity}_period_key')."
+				}
+			},
+			"additionalProperties": false
+		},
+		"traitField": {
+			"type": "object",
+			"description": "Field definition within a trait. Same shape as entity field definitions.",
+			"properties": {
+				"dbDatatype": { "type": "string" },
+				"columnType": { "type": "string" },
+				"fieldTypeCd": { "type": "string" },
+				"flags": { "type": "string" },
+				"isPk": { "type": "boolean" },
+				"isIdentity": { "type": "boolean" },
+				"isNullable": { "type": "boolean" },
+				"formula": { "type": "string" },
+				"orderNum": { "type": "integer" },
+				"description": { "type": "string", "description": "Supports {entity}/{Entity} placeholders" },
+				"maxLen": { "type": "integer" },
+				"link": {
+					"type": "object",
+					"properties": {
+						"entity": { "type": "string" },
+						"thisKey": { "type": "string" },
+						"otherKey": { "type": "string" }
+					},
+					"required": ["entity", "thisKey", "otherKey"],
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		},
+		"traitReference": {
+			"type": "object",
+			"description": "FK reference definition within a trait",
+			"required": ["from", "to"],
+			"properties": {
+				"from": {
+					"type": "object",
+					"required": ["field"],
+					"properties": {
+						"field": { "type": "string" }
+					},
+					"additionalProperties": false
+				},
+				"to": {
+					"type": "object",
+					"required": ["entity", "field"],
+					"properties": {
+						"entity": { "type": "string" },
+						"field": { "type": "string" }
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/resources/schemas/triggers.schema.json

@@ -0,0 +1,59 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/triggers.schema.json",
+	"title": "dForge Module Triggers",
+	"description": "Trigger definitions for a dForge module (logic/triggers.json). A trigger watches an entity for an event (insert/update/delete/status_change/any), evaluates an optional formula condition using `[field]` syntax, and fires an action if true. Different from scheduled jobs (cron-driven) and webhooks (outbound HTTP) — triggers are intra-tenant DB-event-driven action invocations.",
+	"type": "object",
+	"required": ["triggers"],
+	"properties": {
+		"triggers": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/trigger" }
+		}
+	},
+	"additionalProperties": false,
+	"$defs": {
+		"trigger": {
+			"type": "object",
+			"required": ["code", "entity", "event", "action"],
+			"properties": {
+				"code": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9_]*$",
+					"description": "Trigger code, unique within the module."
+				},
+				"description": {
+					"type": "string",
+					"description": "Human-readable description of what the trigger does and when."
+				},
+				"entity": {
+					"type": "string",
+					"description": "Entity whose events this trigger watches. May be cross-module via dot notation (e.g. 'fin.invoice')."
+				},
+				"event": {
+					"type": "string",
+					"enum": ["insert", "update", "delete", "status_change", "any"],
+					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete."
+				},
+				"condition": {
+					"type": "string",
+					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event."
+				},
+				"action": {
+					"type": "string",
+					"description": "Action code to invoke. The action must NOT use record-context (`[field]`) syntax in a way that requires the original triggering record — the trigger passes the record id via params. Cross-module form 'module.action' is supported."
+				},
+				"params": {
+					"type": "object",
+					"description": "Optional static parameters passed to the action at invocation time. Merged with the runtime-injected `record_id` / `record_old` (if event uses old-record diff)."
+				},
+				"async": {
+					"type": "boolean",
+					"default": false,
+					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls). When false, the action runs in the same transaction; failures roll back the original DB change."
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/resources/schemas/webhooks.schema.json

@@ -0,0 +1,73 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Webhooks",
+	"description": "Webhook subscription definitions for a dForge module package (webhooks.json)",
+	"type": "object",
+	"required": ["subscriptions"],
+	"properties": {
+		"subscriptions": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["code", "description", "entity", "event"],
+				"properties": {
+					"code": {
+						"type": "string",
+						"maxLength": 100,
+						"pattern": "^[a-z][a-z0-9_]*$",
+						"description": "Unique identifier within the module"
+					},
+					"description": {
+						"type": "string",
+						"description": "Human-readable description"
+					},
+					"entity": {
+						"type": "string",
+						"description": "Entity code that triggers this webhook"
+					},
+					"event": {
+						"type": "string",
+						"enum": ["insert", "update", "delete", "status_change", "any"],
+						"description": "Event type that fires this webhook"
+					},
+					"condition": {
+						"type": "string",
+						"description": "Formula evaluated against the record. Webhook fires only if true."
+					},
+					"endpointUrl": {
+						"type": "string",
+						"format": "uri",
+						"description": "Default endpoint URL. Integration modules ship with this pre-configured; admin can override."
+					},
+					"secretCd": {
+						"type": "string",
+						"description": "Secret code for API key (from dforge.secret table, admin-configured)"
+					},
+					"payload": {
+						"type": "object",
+						"properties": {
+							"include": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Field codes to include. If omitted, include all visible fields."
+							},
+							"includeOld": {
+								"type": "boolean",
+								"default": false,
+								"description": "Include previous field values on update/status_change events"
+							}
+						},
+						"additionalProperties": false
+					},
+					"enabled": {
+						"type": "boolean",
+						"default": true,
+						"description": "Can be set to false to disable without removing"
+					}
+				},
+				"additionalProperties": false
+			}
+		}
+	},
+	"additionalProperties": false
+}